[Dynamic Language] 用Sphinx自动生成python代码注释文档


pip install -U sphinx

mac-abeen:doc_logic abeen$ sphinx-apidoc --help
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_path, ...]

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

The <exclude_path>s can be files and/or directories that will be excluded
from generation.

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

-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 existing files
-l, --follow-links Follow symbolic links. Powerful when combined with
-n, --dry-run Run the script without creating files
-e, --separate Put documentation for each module on its own page
-P, --private Include "_private" modules
-T, --no-toc Don't create a table of contents file
-E, --no-headings Don't create headings for the module/package packages
(e.g. when the docstrings already contain them)
-M, --module-first Put module documentation before submodule
-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
--version Show version information and exit

sphinx-apidoc [options] -o outputdir packagedir [pathnames]
make html




1: 在src(源码目录)目录上级目录下执行

   sphinx-apidoc -F -o ./apidoc ./src

   在当前目录下新建apidoc目录,生成api文档的文件夹就在此目录下,./src 表示需要生成api文档的目录。

2: 进入apidoc目录 修改conf.py文件 设置代码路径为sys.path.insert(0, os.path.abspath('../src'))
3: 在apidoc目录下执行make html 生成html文件.


Sphinx 标记语法示例
This is a Title
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers!

  • 行内代码 用``code``
  • 简单代码块 在代码块的上一个段落后面加2个冒号,空一行后开始代码块,代码块要缩进.
  • 复杂代码块 使用code-block指导语句,还可以选择列出行号和高亮重点行等.
source code below ::                                             
    void foo()                                                  
source code again                                               
.. code-block:: c                                               
    :emphasize-lines: 3,6                                       
    void foo()                                                  


posted @ 2016-07-08 18:49 ABeen 阅读(...) 评论(...) 编辑 收藏