SphinxAPIDOC¶
简介¶
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN ...]
描述¶
sphinx-apidoc 是一个用于自动生成Sphinx源代码的工具,它使用 autodoc
扩展,以其他自动API文档工具的风格记录整个包。
MODULE_PATH 是要记录的python包的路径,以及 OUTPUT_PATH 是放置生成源的目录。任何 EXCLUDE_PATTERN 给出的是 fnmatch-style 将从生成中排除的文件和/或目录模式。
警告
sphinx-apidoc
生成使用 sphinx.ext.autodoc
记录所有找到的模块。如果任何模块在导入时有副作用,这些将由 autodoc
什么时候? sphinx-build
运行。
如果您记录脚本(与库模块不同),请确保它们的主例程受 if __name__ == '__main__'
条件。
选项¶
- -o <OUTPUT_PATH>¶
放置输出文件的目录。如果它不存在,则创建它。
- -q¶
不要在标准输出上输出任何内容,只将警告和错误写入标准错误。
- -f, --force¶
强制覆盖任何现有生成的文件。
- -l, --follow-links¶
使用符号链接。默认为
False
。
- -n, --dry-run¶
不要创建任何文件。
- -s <suffix>¶
生成的源文件的后缀。默认为
rst
.
- -d <MAXDEPTH>¶
生成的目录文件的最大深度。默认为
4
。
- --tocfile¶
目录文件的文件名。默认为
modules
.
- -F, --full¶
生成一个完整的Sphinx项目 (
conf.py
,Makefile
等)使用与 sphinx-quickstart .
- -e, --separate¶
将每个模块的文档放在自己的页面上。
Added in version 1.2.
- -E, --no-headings¶
不要为模块/包创建标题。例如,当docstring已经包含标题时,这很有用。
- -P, --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
(注意到bar
和foo
是命名空间,而不是模块)。根据PEP-0420递归解释路径。
- -M, --module-first¶
将模块文档放在子模块文档之前。
这些选项用于 --full
指定:
- -a¶
将模块路径附加到sys.path。
项目模板化
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/templates/apidoc
和sphinx/templates/quickstart
)
环境¶
- SPHINX_APIDOC_OPTIONS¶
要追加到生成的选项的逗号分隔列表
automodule
指令。默认为members,undoc-members,show-inheritance
.
也见¶
sphinx-build(1), sphinx-autogen(1)