[Python]파이썬 스핑크스 - 파이썬 코드 문서화 하기

스핑크스(Spinhx)

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

 

설치하기

anaconda prompt를 열어서 설치해줍니다

pip install Sphinx

 

그리고 문서화를 하기 원하는 프로젝트로 이동해서 sphinx-quickstar를 실행합니다.

#prompt 내에서 cd를 이용해 문서화 원하는 프로젝트로 이동

sphinx-quickstar

 

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

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]:

 

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

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

 

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

> Author name(s):

 

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

> Project release []:

 

프로젝트의 언어를 지정합니다. 스핑크스는 여러 언어를 지원하며 기본은 영어(en)입니다. 한국어 문서를 제작하는 경우 (ko)를 사용합니다. 

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
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]:

문서 빌드해보기

이제 cmd 창을 열어서 문서를 빌드 해봅니다.

아까 sphinx-quickstart를 만든 디렉토리로 가서 make html 입력합니다.

make html

 

 

원하는 디렉토리/build/html/index.html로 만들어졌습니다. 

 

 

 

 

 

index.html를 들어가보니 요렇게 만들어졌네요

조금 더 공부해서 문서를 만들어봐야겠습니다.