利用Sphinx为python项目生成文档

Sphinx最初是为python而产生的，用于生成新的python官方文档, 现可支持其它语言.

以下环境都为 Ubuntu14.04+python3.4

安装Sphnix:

$ pip3 search Sphinx

$ pip3 install Sphinx

为项目生成文档(sphinx支持从 .py代码提取docstring来生成文档)

$ cd myproject

$ ls

a.py    b.py    c.py

$  sphinx-quickstart

Enter the root path for documentation.

> Root path for the documentation [.]: doc

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

其它项都选择默认

完成之后，会在当前目录创建 doc 目录. 所有sphinx相关的文件都在 doc目录下

$ ls doc/

_build  conf.py  index.rst  Makefile  _static  _templates

*****************注意**********************

一定要更改 doc/conf.py

$ vi doc/conf.py

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

sys.path.insert(0, os.path.abspath('..'))  #　**IMPORTANT**  缺少此行会导致在make html时提示 __import__出错. 所以必须把上一级目录(即代码所在目录)include进来

生成apidoc

$ sphinx-apidoc -o .doc/ .

Creating file doc/a.rst.

Creating file doc/modules.rst

# 把生成的 doc/modules.rst添加到index.rst

$ vi doc/index.rst

Contents:

.. toctree::

:maxdepth: 2

modules.rst

生成html页面

$ cd doc

$ make html