sphinx-apidoc

概要

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

描述

sphinx-apidoc 是一个自动生成Sphinx源的工具,使用 autodoc 扩展,以其他自动API文档工具的方式记录整个包。

MODULE_PATH 是要记录的Python包的路径,OUTPUT_PATH 是生成的源所在的目录。 给出的任何 EXCLUDE_PATTERNs 是 fnmatch-style 文件和/或将从生成中排除的目录模式。

警告

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

如果您记录脚本(而不是库模块),请确保它们的主例程受 if __name__ == '__main__' 条件的保护。

选项

-o <OUTPUT_PATH>

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

-f, --force

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

-l, --follow-links

遵循符号链接。

-n, --dry-run

不要创建任何文件。

-s <suffix>

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

-d <MAXDEPTH>

生成的目录文件的最大深度。

--tocfile

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

-T, --no-toc

不要创建目录文件。忽略时 --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.pyfoo/bar/baz/__init__.py (注意 barfoo 是命名空间,而不是模块)。

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

-M, --module-first

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

在以下情况下使用这些选项 --full:

-a

将module_path附加到sys.path。

-H <project>

设置项目名称以放入生成的文件中(请参阅 project)。

-A <author>

设置要放入生成文件的作者姓名(参见 copyright)。

-V <version>

设置项目版本以放入生成的文件中(请参阅 version)。

-R <release>

设置项目发布以放入生成的文件(请参阅 release)。

环境

SPHINX_APIDOC_OPTIONS

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

也可以看看

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