MkApi

Module and Package

MkApi can create module and package documentation as well as function and class. Specify a package or module by its full path name.

![mkapi](mkapi.core)
package
mkapi.core

Package level documentation is written in __init__.py.

Module Level Components

As class level attributes, module level attributes can be inspected. Here is the beginning part of google_style.py.

File 1 google_style.py: line number 1-18

"""Module level docstring."""
from dataclasses import dataclass, field
from typing import Dict, Iterator, List, Tuple

#: The first module level attribute. Comment *before* attribute.
first_attribute: int = 1
second_attribute = "abc"  #: str: The second module level attribute. *Inline* style.
third_attribute: List[int] = [1, 2, 3]
"""The third module level attribute. Docstring *after* attribute.

Multiple paragraphs are supported.
"""
not_attribute = 123  # Not attribute description because ':' is missing.


def add(x: int, y: int = 1) -> int:
    """Returns $x + y$.

Although there is no Attributes section in docstring, MkApi automatically creates the section if attributes are correctly documented.

![mkapi](google_style)
module
google_style

Module level docstring.

Attributes
  • first_attribute (int) — The first module level attribute. Comment before attribute.
  • second_attribute (str) — The second module level attribute. Inline style.
  • third_attribute (list of int) — The third module level attribute. Docstring after attribute.
    Multiple paragraphs are supported.
Classes
  • ExampleClass — A normal class.
  • ExampleDataClass — A dataclass.
Functions
  • add(x, y) (int) — Returns x + y.
  • gen(n) (str) — Yields a numbered string.

Furthermore, Classes and Functions sections are also created that display a list of members defined in the module and their short descriptions. The prefix [D] means dataclass and [G] means generator.

Documentation with Heading

The other method to create module documentation is heading. For example,

### ![mkapi](google_style)

create a <h3> tag for the google_style module.

module

google_style

Module level docstring.

Attributes
  • first_attribute (int) — The first module level attribute. Comment before attribute.
  • second_attribute (str) — The second module level attribute. Inline style.
  • third_attribute (list of int) — The third module level attribute. Docstring after attribute.
    Multiple paragraphs are supported.
Classes
  • ExampleClass — A normal class.
  • ExampleDataClass — A dataclass.
Functions
  • add(x, y) (int) — Returns x + y.
  • gen(n) (str) — Yields a numbered string.

If you prefer upper case heading, use the upper filter.

### ![mkapi](google_style|upper)
MODULE

GOOGLE_STYLE

Module level docstring.

Attributes
  • first_attribute (int) — The first module level attribute. Comment before attribute.
  • second_attribute (str) — The second module level attribute. Inline style.
  • third_attribute (list of int) — The third module level attribute. Docstring after attribute.
    Multiple paragraphs are supported.
Classes
  • ExampleClass — A normal class.
  • ExampleDataClass — A dataclass.
Functions
  • add(x, y) (int) — Returns x + y.
  • gen(n) (str) — Yields a numbered string.

Display Members

all filter generates entire module documentation including class and function members. Note that Classes and Functions sections have links to the members.

### ![mkapi](google_style|upper|all)
MODULE

GOOGLE_STYLE

Module level docstring.

Attributes
  • first_attribute (int) — The first module level attribute. Comment before attribute.
  • second_attribute (str) — The second module level attribute. Inline style.
  • third_attribute (list of int) — The third module level attribute. Docstring after attribute.
    Multiple paragraphs are supported.
Classes
Functions
  • add(x, y) (int) — Returns x + y.
  • gen(n) (str) — Yields a numbered string.
function

google_style.add(x, y=1)

Returns x + y.

Parameters
  • x (int) — The first parameter.
  • y (int, optional) — The second parameter. Default=1.
Returns (int)

Added value.

Examples

Examples should be written in doctest format.

>>> add(1, 2)
3

Note

You can use the Admonition extension of MkDocs.

Note

Note section is converted into the Admonition.

generator

google_style.gen(n)

Yields a numbered string.

Parameters
  • n (int) — The length of iteration.
Yields (str)

A numbered string.

class

google_style.ExampleClass(x, y)

A normal class.

Parameters
  • x (list of int) — The first parameter.
  • y (str, int) — The second parameter.
Attributes
  • a (str) — The first attribute. Comment inline with attribute.
  • b (dict(str: int)) — The second attribute. Comment before attribute.
  • c (int, optional) — The third attribute. Docstring after attribute.
    Multiple paragraphs are supported.
  • readonly_property (str) — Read-only property documentation.
  • readwrite_property (list of int) — Read-write property documentation.
Raises
  • ValueError — If the length of x is equal to 0.
Methods
  • message(n) (list of str) — Returns a message list.
method
message(n) → list of str

Returns a message list.

Parameters
  • n (int) — Repetition.
dataclass

google_style.ExampleDataClass(x=0)

A dataclass.

Parameters
  • x (int, optional) — The first parameter.
Attributes
  • x (int) — The first attribute.
  • y (int) — The second attribute.