mkdocs._autodoc extension will allow you to dynamically generate API documentation from your
Python modules and classes within the mkdocs project.
This project is built on a proposed extension system for mkdocs, which currently resides on a mkdocs fork found here. To use this plugin, you will need to clone the forked repository and install it to your environment locally:
$ git clone https://github.com/ProjexSoftware/mkdocs.git $ cd mkdocs $ python setup.py develop
There is no intention to maintain this fork, it is a temporary measure until an extension system exists within
You can install the
mkdocs_autodoc package using
$ pip install mkdocs_autodoc $ easy_install mkdocs_autodoc
To have the content always generated dynamically, without the use of any markdown files, you can use the
autodoc page command. This will allow you to dynamically insert a python module into the page hierarchy
You will need to modify your
mkdocs.yml to include something similar to:
mkdocs_extensions: - mkdocs_autodoc pages: - ['api/autodoc:mkdocs', 'API', 'mkdocs']
When this syntax is invoked on load, the
mkdocs module will be loaded and all of its pages dynamically generated
and added to the server. This option is nice because you will always get your latest documentation, however, if
you use this remotely you will need to configure a virtualenv that can load your package.
You define a page the same way for the
autodoc plugin as you do for any
- [<filename>, <group>, <title>]
However, to trigger the auto-documentation you will need to define
autodoc:<module_name> as your filename. This will trigger the
autodoc plugin to import and document the module defined as
module_name. The resulting documentation will be generated into the path specified for that module. So, in the above example,
'api/audodoc:mkdocs' will document the
mkdocs package into the
The second option is to statically build your API documentation as Markdown files that can be loaded anywhere.
This exists as a command-line extension to the
mkdocs commands, and works similarly, except instead of generating
dynamic HTML content, it will export out *.md files to your documents root. This method will also require
use of the mkdocs_tree extension.
You will need to call this whenever you want to re-generate your API documentation, however it will not need access to your code libraries on remote servers.
You will need to modify your
mkdocs.yml file to include something simliar to:
mkdocs_extensions: - mkdocs_tree - mkdocs_autodoc pages: - ['tree:api/mkdocs', 'API', 'mkdocs']
To use this, you will need to invoke the command from the command line:
$> mkdocs autodoc-generate mkdocs
You can specify
--outpath=/path/to/output which will default to
docs/api as well as
which will be the page's base path (defaulting to
WARNING: This will remove the
outpath before building, so you should always only keep autogenerated docs in it.