TrendingTechnology / mkautodoc

Auto documentation for MkDocs 📘

MkAutoDoc

Python API documention for MkDocs.

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

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