Object mode

MkAPI provides Object mode to embed object documentation in your Markdown source.

Package for demonstration

In this page, we use a demonstration package examples to describe the Object mode of MkAPI. This package includes one subpackage styles and the styles subpackage includes two modules: google.py and numpy.py These two modules are style guides of docstrings copied from Napoleon project site:

• google.py: Example Google Style Python Docstrings

• numpy.py: Example NumPy Style Python Docstrings

The directory structure of the examples package is shown below:

examples/
├─ __init__.py
└─ styles/
   ├─ __init__.py
   ├─ google.py
   └─ numpy.py

Top level Package

First, let's see the top level package examples. To embed the object documentation in a Markdown source, you can write a Markdown syntax like:

::: examples

Three colons (:::) must start at the begging of line, followed by a space (␣) and an object fullname, for example, package.module.function. In the current case, just a pakcage name examples. MkAPI scans the Markdown source to find this syntax pattern and then convert it into the corresponding object documentation like below:

examples [source]

package examples

Example package for MkAPI test.

Note

In the above example, the green dashed border is just guide for eyes to clarify the region of the documentation generated by MkAPI.

In the above example, a horizontal gray line is an object boundary to seperate successive objects. A gray text above the line is the fullname of the object. Below the line, the object kind (package) and (qualified) name (examples) are shown. This part is a heading of the object documentation.

After the heading, main contents of documentation are rendered. Contents of the examples package is just one-line summary for the package:

examples/__init__.py

"""Example package for MkAPI test."""

Package with __all__

A package can have an __all__ attribute to provide names that should be imported when from package import * is encountered. (See "Importing * From a Package" of Python documentation.)

MkAPI recognizes the __all__ attribute and automatically list up the objects and categorizes them by kind (module, class, function, or attribute).

In our example, examples.styles package have the __all__ attribute. Check the output:

::: examples.styles

examples.styles [source]

package examples.styles

Example module for MkAPI test.

Classes

• ExampleClassGoogle — The summary line for a class docstring should fit on one line.

• ExampleClassNumPy — The summary line for a class docstring should fit on one line.

In the above example, examples.styles object documentation has a Classes section that includes two classes: ExampleClassGoogle and ExampleClassNumPy. These names has a link to the object documentation to navigate you. The summary line for classes is also shown for convinience. Below is the source code of examples/styles/__init__.py.

examples/styles/__init__.py

"""Example module for MkAPI test."""
from .google import ExampleClass as ExampleClassGoogle
from .numpy import ExampleClass as ExampleClassNumPy

__all__ = ["ExampleClassGoogle", "ExampleClassNumPy"]

Two modules (google and numpy) have their own class with the same name of ExampleClass. The parent package examples.styles uses import statement with alias name (ExampleClassGoogle or ExampleClassNumPy) to distinct these two classes. The Classes section shows these alias names, but you can check the unaliased fullname by hovering mouse cursor on the names.

Module

Python module has classes, functions, or attributes as its members. A Module documentation can be a docstring of module itself written by the author. MkAPI adds members list automatically.

::: examples.styles.google

examples.styles.google [source]

module examples.styles.google

Example Google style docstrings.

This module demonstrates documentation as specified by the Google Python Style Guide. Docstrings may extend over multiple lines. Sections are created with a section header and a colon followed by a block of indented text.

Example

Examples can be given using either the Example or Examples sections. Sections support any reStructuredText formatting, including literal blocks::

$ python google.py

Section breaks are created by resuming unindented text. Section breaks are also implicitly created anytime a new section starts.

Attributes

• module_level_variable1 : int — Module level variables may be documented in either the Attributes section of the module docstring, or in an inline docstring immediately following the variable.

  Either form is acceptable, but the two should not be mixed. Choose one convention to document module level variables and be consistent with it.

• module_level_variable2 : int — Module level variable documented inline.

  The docstring may span multiple lines. The type may optionally be specified on the first line, separated by a colon.

Todo

• For module TODOs
• You have to also use sphinx.ext.todo extension

Classes

• ExampleError — Exceptions are documented in the same way as classes.

• ExampleClass — The summary line for a class docstring should fit on one line.

• ExamplePEP526Class — The summary line for a class docstring should fit on one line.

Functions

• function_with_types_in_docstring — Example function with types documented in the docstring.

• function_with_pep484_type_annotations — Example function with PEP 484 type annotations.

• module_level_function — This is an example of a module level function.

• example_generator — Generators have a Yields section instead of a Returns section.

Warning

Currently, MkAPI supports a small subset of reStructuredText directives:

• .. code-block::
• .. note::
• .. warning::
• .. deprecated::

The following content must be indented by four spaces.

You can check the corresponding docstring here.

Note

In a Markdown source, you can add a link to (1) documentation or (2) source of an object:

1. [some text][package.module.function]
2. [some text][package.module.function|source]

In a docstring, the module name can be omitted:

import module

def f():
    """[A function][f] or just [f]."""

def g():
    """You can refer [other object][f] as well as [module]."""

Module members

The last part of this page is for module members. The syntax to embed these objects is the same as package or module.

Class

examples.styles.goole module has an ExampleClass class. You can write like below:

::: examples.styles.google.ExampleClass

There is another useful feature. The heading of object documentation contains the fullname of an object. This fullname has hierarchical links to parent objects. In the current case, the fullname is:

examples.styles.google.ExampleClass

Here,

• The first segment examples has a link to the top level pakcage examples.
• The second segment styles has a link to the subpakcage examples.styles.
• The third segment google has a link to the module examples.styles.google.
• The last segment ExampleClass is the corresponding object itself so that a link has been omitted.

You can check these links by hovering mouse cursor on the name segments.

examples.styles.google.ExampleClass [source]

class ExampleClass(param1, param2, param3)

The summary line for a class docstring should fit on one line.

If the class has public attributes, they may be documented here in an Attributes section and follow the same formatting as a function's Args section. Alternatively, attributes may be documented inline with the attribute's declaration (see init method below).

Properties created with the @property decorator should be documented in the property's getter method.

Example of docstring on the init method.

The init method may be documented in either the class level docstring, or as a docstring on the init method itself.

Either form is acceptable, but the two should not be mixed. Choose one convention to document the init method and be consistent with it.

Attributes

• attr1 : str — Description of attr1.

• attr2 : int, optional — Description of attr2.

• readonly_property : str — Properties should be documented in their getter method.

• readwrite_property : list[str] — Properties with both a getter and setter should only be documented in their getter method.

  If the setter method contains notable behavior, it should be mentioned here.

Note

Do not include the self parameter in the Args section.

Parameters

• param1 : str — Description of param1.

• param2 : int, optional — Description of param2. Multiple lines are supported.

• param3 : list(str) — Description of param3.

Methods

• example_method — Class methods are similar to regular functions.

• __special__ — By default special members with docstrings are not included.

• _private — By default private members are not included.

Note

Currently, __special__ and _private members are treated as a normal member.

Functions or attributes can also be embeded in a Markdown source in the same way as described above.

Function

::: examples.styles.google.module_level_function

examples.styles.google.module_level_function [source]

function module_level_function(param1, param2=None, *args, **kwargs)

This is an example of a module level function.

Function parameters should be documented in the Args section. The name of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious.

If *args or **kwargs are accepted, they should be listed as *args and **kwargs.

The format for a parameter is::

name (type): description
    The description may span multiple lines. Following
    lines should be indented. The "(type)" is optional.

    Multiple paragraphs are supported in parameter
    descriptions.

Parameters

• param1 : int — The first parameter.

• param2 : str, optional — The second parameter. Defaults to None. Second line of description should be indented.

• *args — Variable length argument list.

• **kwargs — Arbitrary keyword arguments.

Returns

• bool — True if successful, False otherwise.

  The return type is optional and may be specified at the beginning of the Returns section followed by a colon.

  The Returns section may span multiple lines and paragraphs. Following lines should be indented to match the first line.

  The Returns section supports any reStructuredText formatting, including literal blocks::

  {
      'param1': param1,
      'param2': param2
  }
  

Raises

• ValueError — If param2 is equal to param1.

• AttributeError — The Raises section is a list of all exceptions that are relevant to the interface.

Attribute

::: examples.styles.google.module_level_variable2

examples.styles.google.module_level_variable2

attribute module_level_variable2 : int

Module level variable documented inline.

The docstring may span multiple lines. The type may optionally be specified on the first line, separated by a colon.

Now, you might be wondering if you have to write all of the module members by yourself. Page mode of MkAPI will help you.