sphinx-apidoc

概要

sphinx-apidoc [选项] -o <输出路径> <模块路径> [排除模式 …]

描述

sphinx-apidoc 是一个用于自动生成 Sphinx 源代码的工具,它使用 autodoc 扩展,以其他自动 API 文档工具的风格来记录整个包.

MODULE_PATH 是要记录的 Python 包的路径,而 OUTPUT_PATH 是放置生成源文件的目录.任何给定的 EXCLUDE_PATTERN 都是 fnmatch-style 文件和/或目录模式,这些模式将被排除在生成之外.

警告

sphinx-apidoc 生成使用 sphinx.ext.autodoc 的源文件来记录所有找到的模块.如果任何模块在导入时有副作用,这些副作用将在运行 sphinx-build 时被 autodoc 执行.

如果你记录脚本（相对于库模块）,确保它们的主程序被 if __name__ == '__main__' 条件保护.

选项

-o <OUTPUT_PATH>

要放置输出文件的目录.如果它不存在,则创建它.

-q

不要在标准输出上输出任何内容,只将警告和错误写入标准错误.

-f, --force

强制覆盖任何现有的生成文件.

-l, --follow-links

跟随符号链接.默认为 False.

-n, --dry-run

不要创建或删除任何文件.

-s <suffix>

生成的源文件的后缀.默认为 rst.

-d <MAXDEPTH>

生成的目录文件的最大深度.默认为 4.

--tocfile

目录文件的文件名.默认为 modules.

-T, --no-toc

不要创建目录文件.当提供 --full 选项时忽略.

--remove-old

删除输出目录中不再创建的现有文件.与 --full 选项不兼容.

-F, --full

使用与 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``（注意 ``bar 和 foo 是命名空间,不是模块）.

根据 PEP-0420 递归解释路径.

-M, --module-first

在子模块文档之前放置模块文档.

这些选项在指定 --full 时使用:

-a

将 module_path 附加到 sys.path.

-H <project>

设置要在生成的文件中使用的项目名称（参见 project）.

-A <author>

设置要在生成的文件中放置的作者姓名（见 版权）.

-V <version>

设置项目版本以放入生成的文件中（参见 version）.

-R <release>

设置要在生成的文件中使用的项目版本（参见 release）.

项目模板

Added in version 2.2: sphinx-apidoc 的项目模板选项

-t, --templatedir=TEMPLATEDIR

模板目录用于模板文件.您可以修改由 apidoc 生成的 sphinx 项目文件的模板.允许以下 Jinja2 模板文件:

  • module.rst.jinja

  • package.rst.jinja

  • toc.rst.jinja

  • root_doc.rst.jinja

  • conf.py.jinja

  • Makefile.jinja

  • Makefile.new.jinja

  • make.bat.jinja

  • make.bat.new.jinja

详细信息,请参考Sphinx提供的系统模板文件.（sphinx/templates/apidoc 和 sphinx/templates/quickstart）

环境

SPHINX_APIDOC_OPTIONS

一个以逗号分隔的选项列表,附加到生成的 automodule 指令.默认为 members,undoc-members,show-inheritance.

另见

sphinx-build(1),:manpage:sphinx-autogen(1)