mkdocs-autoapi
is a MkDocs plugin that automatically generates API
documentation from your project's source code. The idea for the plugin comes
from this recipe
in the MkDocs documentation.
pip
We recommend installing this package with pip
:
pip install mkdocs-autoapi
To use the plugin, add the following configuration to your mkdocs.yml
file:
plugins:
- ... other plugin configuration ...
- mkdocs-autoapi
- mkdocstrings
By default, the plugin will use the current working directory as the project
root. If you would like to use a different directory, you can specify a value
in the autoapi_dir
configuration option:
plugins:
- ... other plugin configuration ...
- mkdocs-autoapi:
autoapi_dir: /path/to/autoapi/dir
- mkdocstrings
You can ignore files and directories from the documentation by specifying a
value in the autoapi_ignore
configuration option. This option accepts a list
of glob patterns. Note that the following patterns are always ignored:
**/.venv/**/
**/venv/**/
Likewise, the autoapi_file_patterns
configuration option allows for control of
which files are included in the API reference. This option also accepts a list
of glob patterns which are evaluated (recursively) relative to autoapi_dir
. By
default, all files with .py
and .pyi
extensions are included.
As an example, suppose your project has the following structure:
project/
docs/
index.md
module/
__init__.py
lorem.py
ipsum.py
dolor.py
second_module/
__init__.py
lorem.py
sit.py
amet.py
venv/
mkdocs.yml
README.md
To ignore all files named lorem.py
, you can add the following configuration
to your mkdocs.yml
file:
plugins:
- ... other plugin configuration ...
- mkdocs-autoapi:
autoapi_ignore:
- "**/lorem.py"
autoapi_file_patterns:
- "*.py"
- mkdocstrings
To disable API documentation generation, set the autoapi_generate_api_docs
configuration option to False
. This is useful when transitioning to manual
documentation or when the API documentation is not needed.
The inclusion of API documentation in the navigation can be controlled via the
configuration option autoapi_add_nav_entry
. This option accepts either a
boolean value or a string. Behavior is as follows:
True
, then a section named "API Reference" will be added to the end of
the navigation.False
, then no section for the API documentation will be added. In this
case, a manual link to the API documentation can be added to the navigation.Example: To include the API documentation in the navigation under the section
"Reference", add the following configuration to mkdocs.yml
:
plugins:
- ... other plugin configuration ...
- mkdocs-autoapi:
autoapi_add_nav_entry: Reference
- mkdocstrings
Example: To disable the automatic addition of the API documentation to the
navigation and add a manual link to the API documentation, add the following
configuration to mkdocs.yml
:
nav:
- ... other navigation configuration ...
- API: autoapi/ # target should be `autoapi_root`
- ... other navigation configuration ...
More information on navigation configuration can be found in the MkDocs User Guide.
Again, consider the following project structure:
project/
docs/
index.md
module/
__init__.py
lorem.py
ipsum.py
dolor.py
second_module/
__init__.py
lorem.py
sit.py
amet.py
venv/
mkdocs.yml
README.md
A full mkdocs.yml
for the project might look like this:
site_name: Project
nav:
- Home: index.md
- API Reference: autoapi/
plugins:
- mkdocs-autoapi
- mkdocstrings
theme:
name: readthedocs
More information MkDocs configuration through mkdocs.yml
can be found in the
MkDocs User Guide.
Contributions are always welcome! Please submit a pull request or open an issue to get started.
This project is licensed under the MIT License. See the LICENSE file for more information.