[Dynamic Language] 用Sphinx自动生成python代码注释文档
2016-07-08 18:49
861 查看
用Sphinx自动生成python代码注释文档
pip install -U sphinx
安装好了之后,对Python代码的文档,一般使用sphinx-apidoc来自动生成:
查看帮助
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.
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 existing files
-l, --follow-links Follow symbolic links. Powerful when combined with
collective.recipe.omelette.
-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
documentation
-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]
进入outputdir目录
make html
然后就能在\_build\html文件夹中看到生成好的文档了,还支持查找的功能
注意修改conf.py把项目目录加入,否则生成时找不到模块没法导入
sys.path.append(os.path.abspath('/users/abeen/abeen/**/web'))
Sphinx 标记语法示例
pip install -U sphinx
安装好了之后,对Python代码的文档,一般使用sphinx-apidoc来自动生成:
查看帮助
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.
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 existing files
-l, --follow-links Follow symbolic links. Powerful when combined with
collective.recipe.omelette.
-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
documentation
-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]
进入outputdir目录
make html
然后就能在\_build\html文件夹中看到生成好的文档了,还支持查找的功能
注意修改conf.py把项目目录加入,否则生成时找不到模块没法导入
sys.path.append(os.path.abspath('/users/abeen/abeen/**/web'))
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!
相关文章推荐
- python手记-twisted(3)
- python操作mysql数据库(增删查改)
- python 遍历 list
- python编码与反编码 decode('unicode-escape')
- python 参数
- 存钱问题
- python初步
- 再次mergesort
- python--无界面4*4拼图 游戏
- Python脚本通过unixODBC驱动访问Greenplum(4.3.8.2)数据库安装指导
- Python Web开发——学习笔记
- Python Tutoral 学习笔记7 --Standard Library
- Python访问数据库——学习笔记
- Python电子邮件——学习笔记
- Python常用的第三方模块——学习笔记
- Python常用内建模块——学习笔记
- pyodbc访问数据库(python ODBC访问数据库)
- python下载文件的三种方法
- <python> 匯入excel
- Python使用hashlib模块做字符串加密