自动生成所有子包/模块的API参考

Question

我使用 mkdocs 和 mkdocstrings 插件来生成 Python 包的文档。

我的包裹以标准方式组织

- setup.py
- mkdocs.yaml
- docs/
- mypackage/
  - __init__.py
  - module1.py
  - module2.py
  - subpackage1/
     - __init__.py
     - submodule1.py
     - submodule2.py
- [...]

在mkdocs.yml：

plugins:
  - mkdocstrings
nav:
  - API: references.md

并在references.md：

# API references

::: mypackage

这不会生成任何文档（即“API”页面保持空白）

另一方面，这有效：

::: mypackage.module1

跑步mkdocs build -v：

DEBUG    -  mkdocstrings: Matched '::: mypackage'
DEBUG    -  mkdocstrings: Using handler 'python'
DEBUG    -  mkdocstrings: Collecting data
DEBUG    -  griffe: Found mypackage: loading
DEBUG    -  griffe: Loading path mypackage/__init__.py
DEBUG    -  griffe: Loading path mypackages/module1.py
[...]
DEBUG    -  griffe: Iteration 1 finished, 0 aliases resolved, still 0 to go
DEBUG    -  mkdocstrings: Updating renderer s env
DEBUG    -  mkdocstrings: Rendering templates
DEBUG    -  mkdocstrings: python/templates/material/module.html: Rendering mypackage
DEBUG    -  mkdocstrings: python/templates/material/children.html: Rendering children of mypackage
DEBUG    -  Running 1 `page_content` events
DEBUG    -  mkdocs_autorefs.plugin: Mapping identifiers to URLs for page references.md
[...]
mkdocs_autorefs.plugin: Fixing references in page index.md
DEBUG    -  Building page references.md
DEBUG    -  Running 1 `page_context` events
DEBUG    -  Running 2 `post_page` events
DEBUG    -  mkdocs_autorefs.plugin: Fixing references in page references.md

我不熟悉 mkdocs 和 mkdocstrings，但这似乎并不表明任何错误，并显示找到了源。

我想我错过了什么？（或者我应该手动列出所有模块的路径？）

Answer 1

啊，这是因为默认情况下子模块是不渲染的。尝试将该show_submodules选项设置为 true。全球：

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_submodules: true

本地：

::: mypackage
    options:
      show_submodules: true