利用Sphinx轻松生成python代码的文档

【原文：http://blog.csdn.net/rumswell/article/details/14088121】

【本文章来源于网络，仅作为学习日记之用，版权归原作者所有，如果侵犯了您的权益，请来信告知，我会尽快处理】

======================================================

大名鼎鼎的Numpy,Scipy等python扩展库都是使用Sphinx来自动生成文档的,就连Python的官方帮助文档也是使用Sphinx来发布的,由此可见Sphinx的流行和实用.

对Python代码的文档,一般使用sphinx-apidoc来自动生成:

[plain]  view plain copy

1. $ sphinx-apidoc [options] -o outputdir packagedir [pathnames]  

sphinx-apidoc语法如下:

[plain]  view plain copy

1. Usage: sphinx-apidoc-script.py [options] -o <output_path> <module_path> [exclude_paths, ...]  
2.   
3. Look recursively in <module_path> for Python modules and packages and create  
4. one reST file with automodule directives per package in the <output_path>.  
5.   
6. Note: By default this script will not overwrite already created files.  
7.   
8. Options:  
9.   -h, --help            show this help message and exit  
10.   -o DESTDIR, --output-dir=DESTDIR  
11.                         Directory to place all output  
12.   -d MAXDEPTH, --maxdepth=MAXDEPTH  
13.                         Maximum depth of submodules to show in the TOC  
14.                         (default: 4)  
15.   -f, --force           Overwrite all files  
16.   -n, --dry-run         Run the script without creating files  
17.   -T, --no-toc          Don't create a table of contents file  
18.   -s SUFFIX, --suffix=SUFFIX  
19.                         file suffix (default: rst)  
20.   -F, --full            Generate a full project with sphinx-quickstart  
21.   -H HEADER, --doc-project=HEADER  
22.                         Project name (default: root module name)  
23.   -A AUTHOR, --doc-author=AUTHOR  
24.                         Project author(s), used when --full is given  
25.   -V VERSION, --doc-version=VERSION  
26.                         Project version, used when --full is given  
27.   -R RELEASE, --doc-release=RELEASE  
28.                         Project release, used when --full is given, defaults  
29.                         to --doc-version  

任意选一个扩展包,然后运行以上命令,就可以得到如下图类似的帮助文档:

更高级的设置,大家可以参考官方的帮助文档http://sphinx-doc.org/.