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
