Automatically generate API reference for all subpackages / modules

Question

I am using mkdocs with the mkdocstrings plugin to generate the documentation of my Python package.

My package is organized in a standard fashion

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

in mkdocs.yml:

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

and in references.md:

# API references

::: mypackage

This does not generate any documentation (i.e. the 'API' page remains blanck)

On the other hand, this works:

::: mypackage.module1

Running 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

I am not familiar with mkdocs and mkdocstrings, but it seems this does not indicate any error, and shows the sources are found.

I guess I am missing something? (Or should I manually list the path to all modules?)

Answer 1

Ah, it's because by default submodules are not rendered. Try setting the show_submodules option to true. Globally:

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

Locally:

::: mypackage
    options:
      show_submodules: true