[Python] Sphinx 를 활용하여 Python 문서화해보기!

 

진행환경

MacBook Pro 13inch 2017 / Mac OSX 10.15.4 

 

문서내에 내용은 미리 코드에 작성한 Docstring을 Sphinx가 reStructuredText로 자동으로 파싱하여 사용하므로

미리 코드에 Docstring을 작성하여야합니다.

1. Sphinx 설치하기

pip install Sphinx

위의 명령어로 설치가 가능합니다.

 

2. sphinx-quickstart

먼저 sphinx-quickstart를 희망하는 프로젝트로 이동합니다.

저는 잘 정리되어있지는 않지만 이전에 만들었던 공적마스크 재고 알리미를 문서화해보기로 했습니다.

sphinx-quickstart

다음 명령어를 사용하여 sphinx-quickstart를 실행합니다.

 

2-1. root directory 설정하기

Welcome to the Sphinx 2.1.2 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

보통 여기서 다른 분들은 디렉토리를 설정해주는 것으로 보았는데 여기서는 일단 현재 디렉토리로 자동으로 설정되었습니다.

 

2-2. build directory와 source directory 구분 여부

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

 

2-3. 프로젝트 정보 설정

The project name will occur in several places in the built documentation.
> 프로젝트 이름: 공적마스크 재고 텔레그램 알리미
> 작성자 이름: 장동현
> 프로젝트 출시 버전 []: 1.0

안내하는대로 프로젝트의 이름, 작성자 이름, 프로젝트 출시 버전을 입력합니다.

 

2-4. 문서화 언어 설정

문서를 어떤 언어로 작성할 것인지 설정합니다.

저는 한국어로 작성하려고하여 'ko' 로 설정하였습니다.

영어로 작성할 분들은 'en'으로 설정하면됩니다.

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.
> 프로젝트 언어 [en]: ko

 

그럼 다음과 같이 출력되고 종료됩니다.

Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

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.

 

3. make 명령어를 통해 문서를 빌드해보기!

make html

Sphinx 버전 2.1.2 실행 중
번역을 불러오는 중 [ko]… 완료
making output directory... 완료
빌드 중 [mo]: targets for 0 po files that are out of date
빌드 중 [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                           
오래 된 파일을 찾는 중… 찾은 것이 없습니다
pickling environment... 완료
checking consistency... 완료
preparing documents... 완료
출력을 쓰는 중… [100%] index                                                                                                    
색인 생성 중… genindex
writing additional pages... search
copying static files... 완료
copying extra files... 완료
dumping search index in English (code: en) ... 완료
dumping object inventory... 완료
빌드 성공.

The HTML pages are in build/html.

build 디렉토리 안에 html 디렉토리가 생성되고 그 안에 index.html이 생성됩니다.

 

4. 잘 생성이 되었는지 확인해보기

자동으로 검색까지 가능한 페이지를 만들어주는 것을 확인할 수 있습니다.

 

참고 블로그

파이썬의 스핑크스(Sphinx)를 이용한 문서화

읽어주셔서 감사합니다.