The mkdocs._autodoc extension will allow you to dynamically generate API documentation from your Python modules and classes within the mkdocs project.

Important

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 mkdocs itself.

Installation

You can install mkdocs_autodoc and mkdocs_tree packages using pip or easy_install

$ pip install mkdocs_autodoc mkdocs_tree
$ easy_install mkdocs_autodoc mkdocs_tree

Dynamic Generation

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 at runtime.

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.

Usage

You define a page the same way for the autodoc plugin as you do for any mkdocs page:

- [<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 api directory.

Markdown Generate

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 --basepath=/path/to/base which will be the page's base path (defaulting to api).

WARNING: This will remove the outpath before building, so you should always only keep autogenerated docs in it.