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

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

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

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

sphinx-apidoc语法如下:

Usage: sphinx-apidoc-script.py [options] -o <output_path> <module_path> [exclude_paths, ...]

Look recursively in <module_path> for Python modules and packages and create
one reST file with automodule directives per package in the <output_path>.

Note: By default this script will not overwrite already created files.

Options:
  -h, --help            show this help message and exit
  -o DESTDIR, --output-dir=DESTDIR
                        Directory to place all output
  -d MAXDEPTH, --maxdepth=MAXDEPTH
                        Maximum depth of submodules to show in the TOC
                        (default: 4)
  -f, --force           Overwrite all files
  -n, --dry-run         Run the script without creating files
  -T, --no-toc          Don't create a table of contents file
  -s SUFFIX, --suffix=SUFFIX
                        file suffix (default: rst)
  -F, --full            Generate a full project with sphinx-quickstart
  -H HEADER, --doc-project=HEADER
                        Project name (default: root module name)
  -A AUTHOR, --doc-author=AUTHOR
                        Project author(s), used when --full is given
  -V VERSION, --doc-version=VERSION
                        Project version, used when --full is given
  -R RELEASE, --doc-release=RELEASE
                        Project release, used when --full is given, defaults
                        to --doc-version

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

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