sphinx-doc 을 이용한 개발문서 작성환경 구성

서론

 가을에 제품(WEB, WAS) 출시를 앞두고 정식 메뉴얼을 준비중에 있다. 그동안 alpha test를 위해 컨플루언스에 임시 메뉴얼을 작성해놓고 이를 워드로 Export하여 테스터에게 전달했는데 컨플루언스가 만들어내는 워드가 영 마음에 들지않았다. 그래서 꼭 export하고 다시 디자인을 조정해야 했는데 그 양이 많아 질 수록 그 작업시간이 점점 늘어났다. 추가 변경되는 소프트웨어 제품의 특성상 메뉴얼의 현행화는 또 다른 업무 과중과 소프트웨어 품질에 영향을 미치는 요소다. 대책이 필요했다. 온라인으로 메뉴얼을 제공하고 필요에 따라 문서 파일로 전달할 수 있는 방안이 필요했다.

 우리 CTO와 이 문제를 논의하던 중에 python 개발자들이 즐겨 쓰는 문서 자동화 솔루션(Open source)인 sphinx-doc을 써보자는 의견이 나와 이를 시도 해보기로 했다. 참고로 우리 제품은 python하고 전혀 상관없다. 심지어 필자의 개발환경에는 python 조차 없었다. 원래 sphinx-doc은 python 프로젝트를 기반으로 자동으로 API 문서를 자동으로 만들어주는 것이 주된 역할이다. 그러나 필자가 만들고 있는 솔루션은 JAVA와 C++로 작성된 솔루션이다. 따라서 해당 기능은 이번 글에서 다루지않는다. 

이번 글에서는 사용자가 작성한 reStructedText(.rst) 파일을 소스로 하여 html과 dpf를 만들어내는 과정에 대해 다루려 한다. 이 글에서는 sphinx-doc의 소스 역할을 하는  reStructedText(.rst) 파일 작성법에 대해서도 다루지 않으니 해당 내용은 따로 검색해서 공부하기 바란다. (사실 필자도 아직 잘 모른다.)

 

https://www.sphinx-doc.org

Overview — Sphinx documentation

본론

sphinx-doc 을 이용한 문서 산출물 생성과정

 이 내용은 필자의 이해를 바탕으로 작성된 내용이므로 더 자세한 사항은 공식 홈페이지를 통해 알아보도록 한다.

그림1-shinx-doc 문서 생성 과정

 

 

sphinx-doc은 rst 파일을 소스삼아 html, pdf 등을 만들어내는 솔루션이다. 개발자는 contents를 준비하여 rst 문서를 작성하고 이를 make하는 과정을 거치면 해당 내용의 html 이나 pdf 로 출력된다. 이를 단계 별로 요약 설명한다.

1단계: 문서 프로젝트 생성 

프로젝트 디렉터리를 하나 생성하고 문서 프로젝트 생성(sphinx-quickstart) 명령을 이용해서 프로젝트를 구성한다. (구체적인 실행 방법은 이후 단원에서 자세히 설명한다.)

2단계: 소스 문서 작성

대문 페이지 및 treetoc의 source 역할을 하는 index.rst 를 비롯한 하위 문서 rst 파일을 작성한다.

3단계: 산출 문서 생성

make명령어을 이용하여 html이나 pdf 등의 산출 문서를 만들어 낸다.

sphinx-doc 환경 구성

개발과정이 모두 그렇듯이 이 솔루션 또한 개발 환경을 구성하는데 은근히 많은 시간과 노력을 많이 소비 해야 했다. 사실 필자가 이 문서를 남기는 이유도 여기에 있다. 이 글에서는 필자가 사용하고 있는 mac 기준으로 설명하려 한다.

HW	Apple M1 Pro chipset, 16GB RAM
OS	macOS Montery ver. 12.4

1 . python 설치

sphinx-doc 은 python을 기반으로 동작하는 솔루션이므로 이를 설치해야 하는데 3.6 이상을 요구한다. 

 

https://www.python.org/downloads/ 

Download Python

필자는 여기서 mac 용 python 의 최신버전인 3.10.5 를 다운받아 설치했다.

 

2. MacPorts 설치

공식 홈페이지에서 mac에 설치하는 방식을 3가지 제시하고 있는데 필자는 Homebrew 방식으로 설치했다 실패 했다. 기본 기능은 잘 동작 했으나 커스텀 테마를 적용하는 기능(나중에 설명함) 실행에서 에러가 났다. 정확히 이게 원인이였는지는 모르겠다. 참고 하기 바란다. 그래서 다시 시도한 방법이 MacPorts 를 이용한 설치인데 이 명령은 다음 사이트에서 MacPorts를 다운 받아 설치해야 실행 할 수 있다.

 

www.macports.org

The MacPorts Project -- Home

 3. sphinx-doc 설치

 위에서 설명한대로 필자는 MacPorts 를 이용해서 설치에 성공했다. 설치 명령은 다음과 같다.

sudo port install py38-sphinx

그리고 다음 명령을 순차적으로 하라고 한다.

sudo port select --set python python38
sudo port select --set sphinx py38-sphinx

여기까지 수행하고 나면 기본 설치과정이 모두 끝난 것이다. 

 

4. Mac용 Latex 설치

 pdf 문서를 만들 필요가 없는 분들은 건너뛰어도 되는 과정인데 필자의 경우에는 반드시 PDF 파일 생성이 필요하다. 이를 위해서 반드시 설치해야 하는 항목이다. PDF 와 Latex가 뭔가 연관관계가 있는 모양이다. 암튼 다음 사이트에서 다운 받아 설치 해야 하는데 사이즈가 상당하다. 

 

https://www.tug.org/mactex/

MacTeX - TeX Users Group

 

문서 프로젝트 생성 및 HTML 문서 생성

1. 문서 프로젝트 생성

이제 hello world 를 해볼 차례다. 문서 프로젝트를 만드는 방법이 여러가지가 있는것 같은데 필자는 여러 문서에 소개 되어 있는 sphinx-quickstart 라는 명령으로 문서 프로젝트를 만들었다. 이를 위해 문서 프로젝트 디렉터리를 하나 만들어 두자 shell 에서 해당 디렉터리로 이동하여 다음과 같이 명령어를 입력하고 엔터!

sphinx-quickstart

 

그림2-sphinx 생성 유틸리티 실행

여기서 유틸리티는 몇가지 질문을 한다. 여기서 "원본과 빌드 디렉터릴 분리" 라는 질문에 "y"를 입력했다. 소스 디렉터리를 따로 쓸거냐는 질문인데 그것이 좋겠다 판단 했다. 그리고 나머지는 프로젝트 이름, 작성자 이름 등인데 이는 후에도 conf.py 파일에서 직접 수정이 가능하다. 우리가 한글을 사용해야 하기 때문에 프로젝트 언어를 ko로 설정하는 것도 잊지 말자. 이렇게 문서 프로젝트가 생성되고 나면 아래와 같이 디렉터리 파일등이 생성된 것을 볼 수 있다.

그림3-문서 프로젝트 생성 결과

2. HTML 문서 생성

우리가 IDE를 이용하여 프로그램 언어 프로젝트를 만들었을 때도 마찬가지지만 컴파일을 해야 hellow word를 볼 수 있다. 이 솔루션도 그런 과정이 필요한데 바로 make 명령이다. 먼저 html을 만들어본다. 문서 프로젝트의 root 디렉터리로 가서 다음 명령을 실행한다.

make html

그림4-make html 실행

실행 결과를 콘솔에 친절하게 안내를 하고 있다. 하위 디렉터리 build/html 에 결과물이 있노라고. 파인더에서 보면 해당 디렉터리에 여러 파일이 생성되어 있는데 이중 index.html 이 대문 문서다. 브라우저로 열어보자!

 

그림5-첫 번째 html 결과물

드디어 결과를 봤다. 그런데 못생겼다. 흰 바탕에 검은 글씨 성의 없어 보인다. 이것이 sphinx의 기본 테마이며 다양한 기본 테마와 커스텀 테마를 적용 할 수 있다. 이는 다음에서 자세히 설명한다.

3. 테마 적용

테마를 지정하는 방법은 source/conf.py 를 열어 변경할 수 있다. 해당 문서 하단에 다음과 같은 항목을 확인 할 수 있다.

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

'alabaster'가 기본 테마 이름인데 이를 다른 이름으로 바꿀 수 있다. 별 다른 조치 없이 테마 이름만 변경해서 적용할 수 있는 것들을 builtin theme이라고 한다. 이는 다음 페이지에서 자세히 확인 할 수 있다.

 

https://www.sphinx-doc.org/en/master/usage/theming.html?highlight=theme#builtin-themes 

HTML Theming — Sphinx documentation

하지만 필자 같이 난 여기서 만족 못해 하는 사람들은 자기가 만드는 방법도 있는 것 같고 커스텀 갤러리에서 선택해서 사용할 수도 있다.

https://sphinx-themes.org/

Sphinx Themes Gallery

이 갤러리에 테마를 적용하려면 pip 로 설치를 해야 한다. 마음에 드는 테마를 골랐으면 하나 눌러본다. 테마를 적용 했을때 모습을 정확히 보여주고 이를 설치하는 방법과 적용할 테마 이름을 안내한다.

그림6-커스텀 테마 보기

pip3 install groundwork-sphinx-theme

그리고 conf.py를 다음과 같이 수정한다. 그리고 프로젝트 디렉터리로 이동하여 make html 을 다시 실행해본다.

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'groundwork'

그림7-커스텀 테마 적용

PDF 문서 생성을 위한 설정 및 PDF 문서 생성

1. PDF 문서 생성을 위한 환경 설정 

PDF 문서를 생성하기 위해서는 각 프로젝트의 source/conf.py 파일을 수정해야 한다. (테마를 변경하기 위해 편집 했던 바로 그 파일이다.) 해당 파일을 열어 다음과 같은 항목을 추가 한다. 다시 한번 이야기 하지만 pdf로 문서를 만들어내기 위해서는 Latex 설치가 필수적이다. 이를 건너 뛰었다면 다시 위로 올라가 설치를 먼저 하고 돌아오자.

# -- Options for LaTeX output ------------------------------------------------
latex_engine = 'xelatex'
latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    'papersize': 'a4paper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    'preamble': '',

    'babel': ' ',

    # Latex figure (float) alignment
    #
    'figure_align': 'htbp',


    # kotex config
    'figure_align': 'htbp',

    'fontpkg': r'''
\usepackage{kotex}

% 영문 폰트 설정
\setmainfont[Mapping=tex-text]{나눔고딕}
\setsansfont[Mapping=tex-text]{나눔명조}
\setmonofont{D2Coding}

% 한글 폰트 설정
\setmainhangulfont[Mapping=tex-text]{나눔고딕}
\setsanshangulfont[Mapping=tex-text]{나눔명조}
\setmonohangulfont{D2Coding}

''',
}

PDF라는 것이 HTML과 달리 문서의 물리적인 문서 크기와 사용해야 할 글꼴들과 연관이 되어있기 때문인지 이와 관련된 설정을 하게 되어 있다. 여기서 폰트관련된 설정에 유의해야 하는데 만약 한글 관련된 설정이 누락되면 한글이 깨진다. 또한 여기에 나열된 글꼴이 없는 경우 정상적인 문서 생성이 불가능 하니 미리 글꼴 설치 여부를 확인 해야 한다. conf.py 파일 전문은 이 글에 첨부 했으니 참고 바란다.

 

2. PDF 문서 생성

위와 같이 설정이 준비되었다면 이제 PDF 생성을 해볼 차례다. shell 에서 문서 프로젝트 root 디렉터리로 이동하여 다음과 같은 명령을 실행한다.

make latexpdf

build/latex 디렉터리가 생성되어 있고 그 내에 latex 산출물들과 같이 test3.pdf 파일을 확인 할 수 있다.

그림8-생성된 PDF

결론

사용자에게 전달되는 소프트웨어의 문서는 소프트웨어의 패치, 기능 추가와 같은 업그레이드에 따라 지속적으로 현행화 되어야 하는 요소다. 이런 이유로 요즘 유명한 솔루션들은 문서 파일의 배포를 지양하고 온라인화 하여 제공하는 추세다. 필자는 온라인화 된 문서와 파일로 만들어진 문서 요구를 모두 수용할 수 있는 sphinx-doc을 통해 지속적인 문서 현행화를 추구하려 한다. 비슷한 상황에 놓여 있는 독자분들에게 이 글이 도움이 되었으면 한다.

conf.py

0.00MB