sphinx 로 python api문서 만들기.

1. Sphinx

python 으로 개발을 하면서 javadoc와 같은 역할을 하는 문서생성 툴을 찾다 보니 sphinx가 가장 널리 사용되는 툴이라서 간단한 사용법을 정리한다.

먼저 Sphinx에 대한 소개는 다음과 같다.
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

Sphinx: http://www.sphinx-doc.org/en/stable/index.html
Sphinx autodoc - automated API documentation: http://www.slideshare.net/shimizukawa/sphinx-autodoc-automated-api-documentation-europython-2015-in-bilbao

2.  Sphinx 설치

아래 명령으로 Sphinx를 설치한다.

pip install -U Sphinx

3. 샘플 python project 디렉토리

다음에서 http://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example 샘플 코드를 아래와 같이 생성한다.

testSphinx/

└── an_example_pypi_project

    ├── __init__.py

    ├── useful_1.py

    └── useful_2.py



1 directory, 3 files

4. docs 디렉토리 및 sphinx-quickstart 데이터 생성

4.1 docs 디렉토리 생성

다음과 같이 문서를 저장할 docs디렉토리를 생성한다.

aljeon@aljeon-computing:~/workspace/testSphinx$ ls

an_example_pypi_project

aljeon@aljeon-computing:~/workspace/testSphinx$ mkdir docs

aljeon@aljeon-computing:~/workspace/testSphinx$ cd docs/

4.2 sphinx-quickstart 실행

aljeon@aljeon-computing:~/workspace/testSphinx/docs$ sphinx-quickstart 


Welcome to the Sphinx 1.3.5 quickstart utility.



Please enter values for the following settings (just press Enter to

accept a default value, if one is given in brackets).



Enter the root path for documentation.

> Root path for the documentation [.]: 

=> 현재 docs디렉토리에 있기 때문에 엔터를 친다.



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

=> y를 입력하면 source(설정파일들의 위치)와 build(결과물의 위치)를 분리하고 기본값인 n을 입력하면 하나의 디렉토리에 그대로 저장된다. 관리의 편리성을 위해 y를 입력해 둘을 분리했다.



Inside the root directory, two more directories will be created; "_templates"

for custom HTML templates and "_static" for custom stylesheets and other static

files. You can enter another prefix (such as ".") to replace the underscore.

> Name prefix for templates and static dir [_]: 



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

> Project name: sphinx doc example

> Author name(s): alife.jeon

=> 프로젝트 이름과 작성자를 입력한다.



Sphinx has the notion of a "version" and a "release" for the

software. Each version can have multiple releases. For example, for

Python the version is something like 2.5 or 3.0, while the release is

something like 2.5.1 or 3.0a1.  If you don't need this dual structure,

just set both to the same value.

> Project version: 0.1

> Project release [0.1]: 



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



The file name suffix for source files. Commonly, this is either ".txt"

or ".rst".  Only files with this suffix are considered documents.

> Source file suffix [.rst]: 



One document is special in that it is considered the top node of the

"contents tree", that is, it is the root of the hierarchical structure

of the documents. Normally, this is "index", but if your "index"

document is a custom template, you can also set this to another filename.

> Name of your master document (without suffix) [index]: 



Sphinx can also add configuration for epub output:

> Do you want to use the epub builder (y/n) [n]: 



Please indicate if you want to use one of the following Sphinx extensions:

> autodoc: automatically insert docstrings from modules (y/n) [n]: y

> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y

> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y

> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y

> coverage: checks for documentation coverage (y/n) [n]: y

> pngmath: include math, rendered as PNG images (y/n) [n]: 

> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: 

> ifconfig: conditional inclusion of content based on config values (y/n) [n]: 

> viewcode: include links to the source code of documented Python objects (y/n) [n]: y

=> 필요에 따라 기본값을 그대로 두던가 설정을 변경한다.



A Makefile and a Windows command file can be generated for you so that you

only have to run e.g. `make html' instead of invoking sphinx-build

directly.

> Create Makefile? (y/n) [y]: 

=> Linux 일 경우 y

> Create Windows command file? (y/n) [y]: y

=> Windows 일 경우 y

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.



aljeon@aljeon-computing:~/workspace/testSphinx/docs$ 

4.3 결과

현재까지 진행한 결과 다음과 같은 디렉토리와 파일들이 생긴다.

testSphinx/

├── an_example_pypi_project

│   ├── __init__.py

│   ├── useful_1.py

│   └── useful_2.py

└── docs

    ├── build

    ├── make.bat

    ├── Makefile

    └── source

        ├── conf.py

        ├── index.rst

        ├── _static

        └── _templates



6 directories, 7 files

5. html 문서 생성

docs 디렉토리에서 make html 명령을 수행하면 docs/build/html 아래에 html문서가 생긴다.

aljeon@aljeon-computing:~/workspace/testSphinx/docs$ make html

sphinx-build -b html -d build/doctrees   source build/html

Running Sphinx v1.3.5

making output directory...

loading pickled environment... not yet created

loading intersphinx inventory from https://docs.python.org/objects.inv...

building [mo]: targets for 0 po files that are out of date

building [html]: targets for 1 source files that are out of date

updating environment: 1 added, 0 changed, 0 removed

reading sources... [100%] index                                                                                                                                                                       

looking for now-outdated files... none found

pickling environment... done

checking consistency... done

preparing documents... done

writing output... [100%] index                                                                                                                                                                        

generating indices... genindex

writing additional pages... search

copying static files... done

copying extra files... done

dumping search index in English (code: en) ... done

dumping object inventory... done

build succeeded.

docs/build/html/index.html을 브라우저에서 열여보면 다음과 같은 화면을 볼 수 있다.

하지만 Module Index를 클릭해보면 모듈 API문서가 생성되지 않았음을 확인할 수 있다.

6. 모듈 API 문서 생성

6.1 sphinx-apidoc 수행

모듈 API문서를 생성하기 위해서는 sphinx-apidoc 명령을 통해 각 모듈에 해당하는 rst문서를 만들어주어야 한다.

다음과 같은 명령을 수행한다.

aljeon@aljeon-computing:~/workspace/testSphinx$ sphinx-apidoc -f -o docs/source/ an_example_pypi_project/

Creating file docs/source/an_example_pypi_project.rst.

Creating file docs/source/modules.rst.

결과로 modules.rst와 an_example_pypi_project.rst가 생성된 것을 확인할 수 있다.

testSphinx/

├── an_example_pypi_project

│   ├── __init__.py

│   ├── useful_1.py

│   └── useful_2.py

└── docs

    ├── build

    │   ├── doctrees

    │   │   ├── environment.pickle

    │   │   └── index.doctree

    │   └── html

    │       ├── genindex.html

    │       ├── index.html

    │       ├── objects.inv

    │       ├── search.html

    │       ├── searchindex.js

    │       ├── _sources

    │       │   └── index.txt

    │       └── _static

    │           ├── ajax-loader.gif

    │           ├── alabaster.css

    │           ├── basic.css

    │           ├── comment-bright.png

    │           ├── comment-close.png

    │           ├── comment.png

    │           ├── doctools.js

    │           ├── down.png

    │           ├── down-pressed.png

    │           ├── file.png

    │           ├── jquery-1.11.1.js

    │           ├── jquery.js

    │           ├── minus.png

    │           ├── plus.png

    │           ├── pygments.css

    │           ├── searchtools.js

    │           ├── underscore-1.3.1.js

    │           ├── underscore.js

    │           ├── up.png

    │           ├── up-pressed.png

    │           └── websupport.js

    ├── make.bat

    ├── Makefile

    └── source

        ├── an_example_pypi_project.rst

        ├── conf.py

        ├── index.rst

        ├── modules.rst

        ├── _static

        └── _templates



10 directories, 38 files

6.2 module path 추가

다음으로 docs/source/conf.py 파일을 열고 아래 코드를 추가한다.

sys.path.insert(0, os.path.abspath('../..'))

6.3 html 생성

aljeon@aljeon-computing:~/workspace/testSphinx/docs$ make html

sphinx-build -b html -d build/doctrees   source build/html

Running Sphinx v1.3.5

/media/aljeon/workspace/testSphinx/docs/source

loading pickled environment... done

building [mo]: targets for 0 po files that are out of date

building [html]: targets for 0 source files that are out of date

updating environment: 0 added, 1 changed, 0 removed

reading sources... [100%] an_example_pypi_project                                                                                                                                                     

looking for now-outdated files... none found

pickling environment... done

checking consistency... /media/aljeon/workspace/testSphinx/docs/source/modules.rst:: WARNING: document isn't included in any toctree

done

preparing documents... done

writing output... [100%] modules                                                                                                                                                                      

generating indices... genindex py-modindex

highlighting module code... [100%] an_example_pypi_project                                                                                                                                            

writing additional pages... search

copying static files... done

copying extra files... done

dumping search index in English (code: en) ... done

dumping object inventory... done

build succeeded, 1 warning.



Build finished. The HTML pages are in build/html.

6.4 결과확인

모듈 페이지가 제대로 생성된 것을 확인할 수 있다.

7. 테마 변경

다음의 두 페이지를 참고로 doc 문서의 테마를 변경할 수 있다. 여기서는 sphinx_rtd_theme을 적용하는 것을 정리했다.

• http://www.sphinx-doc.org/en/stable/theming.html
• https://github.com/snide/sphinx_rtd_theme

다음 명령으로 sphinx_rtd_theme를 설치한다.

$ pip install sphinx_rtd_theme

conf.py를 열여서 파일 중간에 html_theme를 찾아 다음 코드로 대체한다.

import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

다시 docs 디렉토리로 가서 make html명령을 수행하고 docs/build/html/index.html을 브라우저에서 열면 다음과 같은 화면을 확인할 수 있다.

8. github sample

샘플 코드들은 github에서 확인할 수 있다.
https://github.com/shjeon78/testSphinx

참고:

Quick Sphinx documentation for Python: http://scriptsonscripts.blogspot.kr/2012/09/quick-sphinx-documentation-for-python.html
Sphinx for Python documentation: http://gisellezeno.com/tutorials/sphinx-for-python-documentation.html