sphinx-apidoc¶
概要¶
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]
说明¶
sphinx-apidoc is a tool for automatic generation of Sphinx sources
that, using the autodoc
extension, document a whole
package in the style of other automatic API documentation tools.
MODULE_PATH*是Python包文档的路径,*OUTPUT_PATH*是所生成源代码所在的目录。任何*EXCLUDE_PATTERNs都是`fnmatch-style`_ 文件和(或)目录模式,这些模式将被排除在生成过程之外。
警告
sphinx-apidoc
生成源文件,这些文件使用:mod: ‘ sphinx.ext.的来记录所有找到的模块。如果任何模块对导入有副作用,则在运行“sphinx-build”时,将由“autodoc”执行这些副作用。
如果你要引入脚本(而不是库模块),确保主程序 main 有这个条件保护:“if __name__ == ‘__main__’”。
选项¶
- -o <OUTPUT_PATH>¶
放置输出文件的目录。如果它不存在,就创建它。
- -q¶
不要在标准输出中输出任何东西,只在标准错误中写入警告和错误。
- -f, --force¶
强制覆盖任何现有生成的文件。
- -l, --follow-links¶
Follow symbolic links. Defaults to
False
.
- -n, --dry-run¶
不要创建任何文件。
- -s <suffix>¶
生成的源文件的后缀。默认为“rst”。
- -d <MAXDEPTH>¶
Maximum depth for the generated table of contents file. Defaults to
4
.
- --tocfile¶
目录文件的文件名。默认为“modules” 。
- -T, --no-toc¶
不要创建目录文件。忽略提供的:option:——full。
- -F, --full¶
使用与:program:sphinx-quickstart`相同的机制生成一个完整的Sphinx项目(``conf.py`,
Makefile
等)。
- -e, --separate¶
将每个模块的文档放在自己的页面上。
Added in version 1.2.
- -E, --no-headings¶
不要为模块/包创建标题。这是有用的,例如,当文档字符串已经包含标题。
- -P, --private¶
包括 “_private” 模块。
Added in version 1.2.
- --implicit-namespaces¶
默认情况下,sphinx-apidoc 只处理 sys.path 中找到的模块。从 Python 3.3 起,引入了 PEP 420 隐式命名空间,允许模块路径结构,比如“foo/bar/module.py”或者 “foo/bar/baz/__init__.py” (注意这里的“foo”和“bar”都用来表示命名空间,并不是模块)。
根据PEP-0420递归地解释路径。
- -M, --module-first¶
在子模块文档之前放置模块文档。
在以下情况下使用这些选项 --full
:
- -a¶
把 module_path 添加到 sys.path。
- -H <project>¶
设置要放入生成文件的项目名称,参阅:confval:project。
项目模板
Added in version 2.2: sphinx-apidoc的项目模板选项
- -t, --templatedir=TEMPLATEDIR¶
模板文件的模板目录。您可以修改apidoc生成的sphinx项目文件的模板。允许以下Jinja2模板文件:
module.rst_t
package.rst_t
toc.rst_t
root_doc.rst_t
conf.py_t
Makefile_t
Makefile.new_t
make.bat_t
make.bat.new_t
详细信息,请参考Sphinx提供的系统模板文件。(“sphinx/模板/apidoc”和“sphinx/模板/快速入门”)
环境¶
- SPHINX_APIDOC_OPTIONS¶
一个逗号分隔的选项列表,附加到生成的“automodule”指令。默认为“members,undoc-members,show-inheritance”。
另请参阅¶
sphinx-build(1), sphinx-autogen(1)