MkApi

MkApi plugin for MkDocs generates API documentation for Python code. MkApi supports two styles of docstrings: Google and NumPy.

Features of MkApi are:

Type annotation: If you write your function such as def func(x: int) -> str:, you don't need write type(s) in Parameters, Returns, or Yields section again. You can overwrite the type annotation in the corresponding docstring.
Object type inspection: MkApi plugin creates class, dataclass, function, or generator prefix for each object.
Attribute inspection: If you write attributes with description as comment in module or class, Attributes section is automatically created.
Docstring inheritance: Docstring of a subclass can inherit parameters and attributes description from its superclasses.
Table of Contents: Table of contents are inserted into the documentation of each package, module, and class.
Page mode: Comprehensive API documentation for your project, in which objects are linked to each other by type annotation.
Bidirectional Link: Using the Page mode, bidirectional links are created between documentation and source code.

Installation

Install the plugin using pip:

pip install mkapi

Configuration

Add the following lines to mkdocs.yml:

plugins:
  - search # necessary for search to work
  - mkapi

Usage

MkApi provides two modes to generate API documentation: Embedding mode and Page mode.

Embedding Mode

To generate the API documentation in a Markdown source, add an exclamation mark (!), followed by mkapi in brackets, and the object full name in parentheses. Yes, this is like adding an image. The object can be a function, class, or module.

![mkapi](<package.module.object>)

You can combine this syntax with Markdown heading:

## ![mkapi](<package.module.object>)

MkApi imports objects that you specify. If they aren't in the sys.path, configure mkdocs.yml like below:

plugins:
  - search
  - mkapi:
      src_dirs: [<path1>, <path2>, ...]

Here, pathXs are inserted to sys.path. These pathXs must be relative to the mkdocs.yml directory.

The embedding mode is useful to embed an object interface in an arbitrary position of a Markdown source. For more details, see:

Page Mode

Using the page mode, you can construct a comprehensive API documentation for your project. You can get this powerful feature by just one line:

nav:
  - index.md
  - API: mkapi/api/mkapi

For more details, see Page Mode and Internal Links

tony / mkapi