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.
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
Although there is no Attributes section in docstring, MkApi automatically creates the section if attributes are correctly documented.
google_style
Module level docstring.
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.
ExampleClass
— A normal class.ExampleDataClass
— A dataclass.
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,
create a <h3>
tag for the google_style
module.
google_style
Module level docstring.
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.
ExampleClass
— A normal class.ExampleDataClass
— A dataclass.
add
(
x
,y
)
(int) — Returns x + y.gen
(
n
)
(str) — Yields a numbered string.
If you prefer upper case heading, use the upper
filter.
GOOGLE_STYLE
Module level docstring.
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.
ExampleClass
— A normal class.ExampleDataClass
— A dataclass.
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.
GOOGLE_STYLE
Module level docstring.
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.
ExampleClass
— A normal class.ExampleDataClass
— A dataclass.
google_style.
add
(
x
, y=1
)
Returns x + y.
x
(int) — The first parameter.y
(int, optional) — The second parameter. Default=1.
Added value.
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.
google_style.
gen
(
n
)
Yields a numbered string.
n
(int) — The length of iteration.
A numbered string.
google_style.
ExampleClass
(
x
, y
)
A normal class.
x
(list of int) — The first parameter.y
(str, int) — The second parameter.
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.
ValueError
— If the length ofx
is equal to 0.
message
(
n
)
(list of str) — Returns a message list.
message
(
n
)
→ list of strReturns a message list.
n
(int) — Repetition.
google_style.
ExampleDataClass
(
x=0
)
A dataclass.
x
(int, optional) — The first parameter.
x
(int) — The first attribute.y
(int) — The second attribute.