Google Style
Let's start concrete examples. Here, a sample Python file google_style.py
is stored under the examples
directory relative to the mkdocs.yml
directory, so we would configure mkdocs.yml
like below. In addition, we add an extension and extra javascript for Arithmatex.
Function
The google_style
module defines a simple function add()
.
Code 1 google_style.add()
def add(x: int, y: int = 1) -> int:
"""Returns $x + y$.
Args:
x: The first parameter.
y: The second parameter. Default={default}.
Returns:
Added value.
Examples:
Examples should be written in doctest format.
>>> add(1, 2)
3
!!! note
You can use the [Admonition extension of
MkDocs](https://squidfunk.github.io/mkdocs-material/extensions/admonition/).
Note:
`Note` section is converted into the Admonition.
"""
return x + y
Then, write a tag anywhere in your Markdown source:
MkApi generates the documentation for the add()
function.
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.
Note
In the above example, green dashed border lines are just guide for the eye to show the region of the documentation generated by MkApi for convenience.
In this simple example, you can see some features of MkApi.
- Use of type annotation for both Parameters and Returns sections.
- Add "optional" if parameters have default values.
- Default value replacement by the
{default}
keyword in the Parameters section. - External hyperlink.
- Use of MkDocs extensions: MathJax rendering and admonition.
Generator
The google_style
module also defines a simple generator gen()
.
Code 2 google_style.gen()
def gen(n) -> Iterator[str]:
"""Yields a numbered string.
Args:
n (int): The length of iteration.
Yields:
A numbered string.
"""
for x in range(n):
yield f"a{x}"
Then,
creates the documentation for the gen()
generator.
google_style.
gen
(
n
)
Yields a numbered string.
n
(int) — The length of iteration.
A numbered string.
In this simple example, note that:
- Type inspection of
gen()
(generator prefix is added beforegoogle_style.gen
). - The parameter
n
has no type annotation but you can specify it in the Parameters section directly. - Yields type is not "iterator of str" but "str", because the
gen()
is a generator.
Class
The google_style
module also defines a simple class ExampleClass
.
Code 3 google_style.ExampleClass
class ExampleClass:
"""A normal class.
Args:
x: The first parameter.
y: The second parameter.
Raises:
ValueError: If the length of `x` is equal to 0.
"""
def __init__(self, x: List[int], y: Tuple[str, int]):
if len(x) == 0:
raise ValueError()
self.a: str = "abc" #: The first attribute. Comment *inline* with attribute.
#: The second attribute. Comment *before* attribute.
self.b: Dict[str, int] = {"a": 1}
self.c = None
"""int, optional: The third attribute. Docstring *after* attribute.
Multiple paragraphs are supported."""
self.d = 100 # Not attribute description because ':' is missing.
def message(self, n: int) -> List[str]:
"""Returns a message list.
Args:
n: Repetition.
"""
return [self.a] * n
@property
def readonly_property(self):
"""str: Read-only property documentation."""
return "readonly property"
@property
def readwrite_property(self) -> List[int]:
"""Read-write property documentation."""
return [1, 2, 3]
@readwrite_property.setter
def readwrite_property(self, value):
"""Docstring in setter is ignored."""
As usual,
creates the documentation for the ExampleClass
class.
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.
In this example, note that:
- Type annotation using
typing
package (List
andTuple
in this case) is converted into readable style. - Attributes section is inserted with type and description. These information is collected from the source code.
- If callable objects have neither Returns nor Yields, the type appears on the object signature line like type annotation.
- Properties are moved to the Attributes section with [RO] or [RW] prefix that indicates whether the property is read-only or read-write.
- Methods section is newly created that displays a list of methods defined in this class. Note that it has a hyperlink to the object.
Note
Although you can write the docstring for a class in the __init__()
function, the attribute inspection only works when you write it as a class level docstring.
Method
You can select a method of class (or any other object that can have docstring) to generate the documentation.
creates the documentation for the message()
of ExampleClass
class.
message
(
n
)
→ list of strReturns a message list.
n
(int) — Repetition.
Data Class
The google_style
module also defines a simple data class ExampleDataClass
.
Code 4 google_style.ExampleDataClass
@dataclass
class ExampleDataClass:
"""A dataclass.
Args:
x: The first parameter.
Attributes:
x: The first attribute.
y: The second attribute.
"""
x: int = 0
y: int = field(default=1, init=False)
Then,
creates the documentation for the ExampleDataClass
class.
google_style.
ExampleDataClass
(
x=0
)
A dataclass.
x
(int, optional) — The first parameter.
x
(int) — The first attribute.y
(int) — The second attribute.
In this example, note that:
- A dataclass prefix instead of a class prefix.
- Attributes type inspection as well as parameters if they are data class fields.
Note
The Napoleon project provides complete examples:
Heading Mode
The other mode to create documentation is heading. For example,
create a <h2>
tag for the google_style.ExampleClass
.
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 str
Returns a message list.
n
(int) — Repetition.
Note that an ExampleClass item in nav menu is created.