sphinx-apidoc

概要

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

说明

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

MODULE_PATH 是Python包文档的路径，OUTPUT_PATH 是所生成源代码所在的目录。任何 EXCLUDE_PATTERN s都是 fnmatch-style 文件和（或）目录模式，这些模式将被排除在生成过程之外。

警告

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

如果你要引入脚本（而不是库模块），确保主程序 main 有这个条件保护： 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 中搜索包含 __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)