sphinx apidoc/autodoc 不会在侧边栏或目录中创建“子模块”和“子包”组

Question

我正在使用 sphinx-rtd-主题。 在 autodoc 生成的页面的侧边栏和目录中，目录和文件被分组为特殊的“子包”和“子模块”类别，如下所示：

my_package
    subpackages
        sp1
            submodules
                sp1_sm1
                sp1_sm2
        sp2
            submodules
                sp2_sm1
                sp2_sm2
    submodules
        sm1
        sm2
    

有没有办法跳过这些分组，使其简单地组织为：

my_package
    sp1
        sp1_sm1
        sp1_sm2
    sp2
        sp2_sm1
        sp2_sm2
    sm1
    sm2

Answer 1

实现此目的的方法是在生成

sphinx-apidoc

文件时修改

.rst

使用的模板。

为此，您可以使用默认模板，复制它们，然后根据需要进行修改。 如果您使用的是虚拟环境，则可以在

sphinx/templates/apidoc

目录中找到它们，如果这对您来说很麻烦，这里有来自 github 的模板链接。

假设您已将文档拆分为

source

和

build

目录，您的

docs

目录如下所示：

docs
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

将默认模板复制到

source/_templates

目录中。

例如，如果您想删除

Subpackages

，您会发现在包的默认模板

package.rst.jinja

中，第 30-35 行有：

{%- if subpackages %}
Subpackages
-----------

{{ toctree(subpackages) }}
{% endif %}

只需在模板的本地副本中将这些行更改为以下内容：

{%- if subpackages %}
{{ toctree(subpackages) }}
{% endif %}

子模块也是如此。

我们可以使用

.rst

生成

apidoc

文件的调用应包含

_templates

目录。 让

PROJECTNAME

成为一个带有项目名称的环境变量。鉴于您当前的目录是

docs

并且您位于适合该项目的虚拟环境中，生成必要的

.rst

文件的调用将如下所示：

sphinx-apidoc -o source/$(PROJECTNAME) --templatedir=source/_templates ../src/$(PROJECTNAME)

我希望这有帮助！