/ Documentation

Python API documention for MkDocs

Python API documention for MkDocs

MkAutoDoc

Python API documention for MkDocs.

This markdown extension adds autodoc style support, for use with MkDocs.

MkAutoDocc

Usage

1. Include the extension in you mkdocs.yml config file:

[...]
markdown_extensions:
  - admonition
  - codehilite
  - mkautodoc

2. Ensure the library you want to document is importable.

This will depend on how your documentation building is setup, but
you may need to use pip install -e . or modify PYTHONPATH in your docs build script.

3. Use the ::: block syntax to add autodoc blocks to your documentation.

# API documentation

::: my_library.some_function
    :docstring:

::: my_library.SomeClass
    :docstring:
    :members:

4. Optionally, add styling for the API docs

Update your mkdocs.yml to include some custom CSS.

[...]
extra_css:
    - css/custom.css

Then add a css/custom.css file to your documentation.

div.autodoc-docstring {
  padding-left: 20px;
  margin-bottom: 30px;
  border-left: 5px solid rgba(230, 230, 230);
}

div.autodoc-members {
  padding-left: 20px;
  margin-bottom: 15px;
}

Notes

The :docstring: declaration.

Renders the docstring of the associated function, method, or class.

The :members: declaration.

Renders documentation for member attributes of the associated class.
Currently handles methods and properties.
Instance attributes set during __init__ are not currently recognised.

May optionally accept a list of member attributes that should be documented. For example:

::: my_library.SomeClass
    :docstring:
    :members: currency vat_registered calculate_expenses

GitHub