Python 패키지 개발일지 06: 스핑크스를 사용한 패키지 문서화

스핑크스(Sphinx)는 파이썬 프로젝트를 문서화하는 도구입니다. 스핑크스는 RST(reStructuredText)와 파이썬의 문서화 문자열을 이용해 매뉴얼과 레퍼런스 문서를 작성하며 문서를 정적 웹페이지, 이북, PDF 등으로 출력합니다.

스핑크스 시작하기

> pip install Sphinx

아나콘다의 경우,

> conda install -c anaconda sphinx

를 사용해 스핑크스를 설치합니다.

빠른 시작

프로젝트 디렉토리에서 다음 명령을 입력합니다.

sphinx-quickstart

이제 스핑크스는 초기화를 위해 몇 가지를 물어봅니다.

You have two options for placing the build directory for
Sphinx output.
Either, you use a directory "_build" within the root path,
or you separate "source" and "build" directories within the
root path.
> Separate source and build directories (y/n)[n]:

y를 입력하면 문서의 내용을 작성한 파일이 들어가는 source 디렉토리와 출력을 지정하는 build디렉토리가 별도로 생성됩니다. n을 입력하면 프로젝트 최상위 디렉토리가 source역할을 하고, 별도의 _build 디렉토리에 결과물을 출력합니다. y를 추천하고, 이것을 기준으로 설명을 이어갑니다.

The project name will occur in several places in the built
documentation.
> Project name: 

프로젝트의 이름을 물어봅니다. 프로젝트의 이름은 문서에 여러 장소에 사용합니다. 파이썬 패키지의 사용자 문서를 만드는 경우 패키지의 이름을 프로젝트 이름으로 정하는 것이 편합니다.

> Author name(s):

작성자의 이름이나 닉네임을 입력합니다. 여러명일 경우 쉼표로 구분합니다.

> Project release []:

프로젝트의 출시버전을 입력합니다. 후에 변경할 수 있으니 지금 기억나지 않는다고 당황할 필요는 없습니다.

If the documents are to be written in a language other than
English, you can select a language here by its language code.
Sphinx will then translate text that it generates into that 
language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/\
configuration.html#confval-language.       
> Project language [en]:

프로젝트의 언어를 지정합니다. 스핑크스는 여러 언어를 지원하며 기본은 영어(en)입니다. 한국어 문서를 제작하는 경우 (ko)를 사용합니다. 지원하는 모든 언어를 보려면 이곳을 참고하세요.

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst
and create other documentation source files. Use the Makefile
to build the docs, like so:
   make builder
where "builder" is one of the supported builders,
e.g. html, latex or linkcheck.      

초기설정이 끝났습니다.

시험삼아 빌드 해보기

{root}/
  ├─ build/
  ├─ source/
  │    ├─ _static/
  │    ├─ _template/
  │    ├─ conf.py
  │    └─ index.rst
  ├─ Makefile
  └─ make.bat

sphinx-quickstart가 만든 파일과 디렉토리는 위와 같습니다. 루트 디렉토리의 명령창(파워쉘이나 CMD)에서 아래 명령을 입력합니다.

./make html

스핑크스가 작업을 완료하면 {root}/build/html/index.html가 만든 문서의 첫 페이지가 됩니다.

시험 빌드를 한 결과물

다음은 레퍼런스 문서를 만드는 작업입니다.