spinxcontrib-apidoc 0.5.0

在conf.py中配置apidoc_module_dir

使用autodoc_tree功能，API文档总是为包含setup.cfg的目录生成，通常是顶级目录。使用此扩展时，您必须显式指定要为其生成文档的目录，使用apidoc_module_dir设置。您应该配置此设置以指向实际的包而不是顶级目录，这意味着您不需要担心跳过不相关的文件，如setup.py。

在conf.py中配置apidoc_excluded_paths

在 conf.py 中的 apidoc_excluded_paths 设置与在 setup.cfg 中的 [pbr] autodoc_tree_excludes 设置的工作方式完全相同；也就是说，它是一个描述相对于源目录要排除的文件和目录的 fnmatch 风格的路径列表。这意味着您可以使用 [pbr] autodoc_tree_excludes 设置中的值，尽管如果您已将 apidoc_module_dir 配置为指向顶级目录以外的其他目录，可能需要更新这些值。

在 conf.py 中配置 apidoc_output_dir

在 conf.py 中的 apidoc_output_dir 设置与在 setup.cfg 中的 [pbr] api_doc_dir 设置的工作方式完全相同；也就是说，它是一个相对于文档源目录的路径，所有 API 文档都应该写入该路径。您可以直接复制 [pbr] api_doc_dir 设置中的值。

从 setup.cfg 中删除设置

从 setup.cfg 文件的 [pbr] 部分删除以下设置

• autodoc_tree_index_modules

• autodoc_tree_excludes

• api_doc_dir

如果您希望使用 sphinx-build 来构建文档，还可能需要删除整个 [build_sphinx] 部分。

在conf.py中配置apidoc_module_dir

使用 autodoc 功能时，API 文档始终为 setup.cfg 所在的目录生成，这通常是顶级目录。使用此扩展时，必须使用 apidoc_module_dir 设置显式指定要为哪个目录生成文档。应将此配置为指向您的实际包而不是顶级目录，因为这意味着您不必担心跳过诸如 setup.py 这样的无关文件。

在conf.py中配置apidoc_excluded_paths

在 conf.py 中的 apidoc_excluded_paths 设置与在 setup.cfg 中的 [pbr] autodoc_exclude_modules 设置不同，前者是 fnmatch 风格的 文件路径 列表，而后者是 fnmatch 风格的 模块路径 列表。因此，您可以重用 [pbr] autodoc_exclude_modules 设置中的大多数值，但您必须从 x.y 格式切换到 x/y 格式。如果您已将 apidoc_module_dir 配置为指向顶级目录以外的其他目录，可能还需要更新这些路径。

在 conf.py 中配置 apidoc_output_dir

在 conf.py 中的 apidoc_output_dir 设置与在 setup.cfg 中的 [pbr] api_doc_dir 设置的工作方式完全相同；也就是说，它是一个相对于文档源目录的路径，所有 API 文档都应该写入该路径。您可以直接复制 [pbr] api_doc_dir 设置中的值。

在 conf.py 中配置 apidoc_separate_modules=True

默认情况下，sphinx-apidoc 为每个包生成一个文档，而 autodoc 为每个（子）模块生成一个文档。通过将此属性设置为 True，我们确保使用后者行为。

将 autoindex.rst 的引用替换为 modules.rst

自动文档（autodoc）功能在输出目录中生成一个名为 autoindex.rst 的文件中的模块列表。相比之下，sphinx-apidoc 和此扩展将此文件称为 modules.rst。您必须将所有对 autoindex.rst 的引用更新为 modules.rst。您还可能希望配置任何包含此文档的 toctree 的 depth 选项，因为 modules.rst 是嵌套的。

从 setup.cfg 中删除设置

从 setup.cfg 文件的 [pbr] 部分删除以下设置

• autodoc_index_modules

• autodoc_exclude_modules

• api_doc_dir

如果您希望使用 sphinx-build 来构建文档，还可能需要删除整个 [build_sphinx] 部分。