Sphinx最初是為python而產(chǎn)生的，用于生成新的python官方文檔, 現(xiàn)可支持其它語(yǔ)言.

以下環(huán)境都為 Ubuntu14.04+python3.4

安裝Sphnix:

$ pip3 search Sphinx

$ pip3 install Sphinx

為項(xiàng)目生成文檔(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

其它項(xiàng)都選擇默認(rèn)

完成之后，會(huì)在當(dāng)前目錄創(chuàng)建 doc 目錄. 所有sphinx相關(guān)的文件都在 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**? 缺少此行會(huì)導(dǎo)致在make html時(shí)提示 __import__出錯(cuò). 所以必須把上一級(jí)目錄(即代碼所在目錄)include進(jìn)來

生成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頁(yè)面

$ cd doc

$ make html