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 项目（conf.py, Makefile 等），使用与 sphinx-quickstart 相同的机制。

-e, --separate

将每个模块的文档放在单独的页面上。

版本 1.2 新增。

-E, --no-headings

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

-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)