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.
Install the plugin using pip:
Add the following lines to
MkApi provides two modes to generate documentation: Embedding mode and Page mode.
To generate the documentation from docstring 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, etc.
You can combine this syntax with Markdown heading:
MkApi imports modules that you specify. If they aren't in the
mkdocs.yml like below:
pathXs are inserted to
pathXs are relative to the
The embedding mode is useful to embed documentation of an object in an arbitrary position of a Markdown source. For more details, see:
Using the page mode, you can construct a comprehensive API documentation for your project. You can get this powerful feature by just one line:
For more details, see Page Mode and Internal Links