sphinx-apidoc

提要

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]

描述

sphinx-apidoc 是一个用于自动生成 Sphinx 源文件的工具，它使用 autodoc 扩展，以其他自动 API 文档工具的风格文档化整个包。

MODULE_PATH 是要文档化的 Python 包的路径，而 OUTPUT_PATH 是生成源文件的目录。任何给定的 EXCLUDE_PATTERN 都是 fnmatch 风格的 文件和/或目录模式，它们将从生成中排除。

警告

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

将每个模块的文档放在其自己的页面上。

版本 1.2 中新增。

-E, --no-headings

不为模块/包创建标题。这在例如 docstrings 中已经包含标题时很有用。

-P, --private

包含“_private”模块。

版本 1.2 中新增。

--implicit-namespaces

如果没有此选项，sphinx-apidoc 会在 sys.path 中搜索包含 __init__.py 文件的 Python 包，或单个文件 Python 模块。

此选项改为使用 PEP 420 隐式命名空间，它允许诸如 foo/bar/module.py 或 foo/bar/baz/__init__.py（请注意 bar 和 foo 是命名空间，而不是模块）之类的布局路径。

-M, --module-first

将模块文档放在子模块文档之前。

当指定 --full 时使用这些选项

-a

将 module_path 附加到 sys.path。

-H <project>

设置要放入生成文件中的项目名称（参见 project）。

-A <author>

设置要放入生成文件中的作者姓名（参见 copyright）。

-V <version>

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

-R <release>

设置要放入生成文件中的项目发布版本（参见 release）。

项目模板

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), sphinx-autogen(1)