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 记录所有找到的模块的源文件。如果任何模块在导入时具有副作用，则 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。

-T, --no-toc

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

--remove-old

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

-F, --full

使用与 sphinx-quickstart 相同的机制生成完整的 Sphinx 项目（conf.py、Makefile 等）。

-e, --separate

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

版本 1.2 中新增。

-E, --no-headings

不要为模块/包创建标题。例如，当文档字符串已包含标题时，这很有用。

-P, --private

包含“_private”模块。

版本 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>

设置要放入生成文件中的作者名称（参见 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)