Skip to content

Page mode

MkAPI provides Page mode to construct a comprehensive API documentation for your Python project.

Use of the Page mode is very simple. Just add a single line to nav section in mkdocs.yml:

mkdocs.yml
nav:
  - index.md  # normal page.
  - $api/package.module  # MkAPI page with a special syntax.

Here, a leading $ is a marker to indicate that this page should be processed by MkAPI to generate API documentation. A text between the leading $ and the last / is used as a name of API directory as well as the prefix of URI. In this case, MkAPI creates two directories api and src in a docs directory. api is for documentation and src is for source code. Module page(s) will be located under these directories automatically:

.
├─ docs/
│  ├─ api/
│  │  └─ package
│  │     └─ module.md
│  ├─ src/
│  │  └─ package
│  │     └─ module.md
│  └─ index.md
└─ mkdocs.yml

You can change the directory name for source code by splitting the prefix with a colon:

mkdocs.yml
nav:
  - index.md
  - $api:src/package.module

Note

  • You can change the names api and src as long as it is a valid directory name and it does not exist.
  • Both api and src directories will be removed after building documentation by MkDocs.

In the above example, just one api/package/module.md file for documentation and one src/package/module.md file for source code will be created. In order to obtain a collection of subpackages/submodules, you can use * symbols. Consider next directory structure:

package/
├─ subpackage1/
│  ├─ __init__.py
│  ├─ module_11.py
│  └─ module_12.py
├─ subpackage2/
│  ├─ __init__.py
│  ├─ module_21.py
│  └─ module_22.py
├─ __init__.py
├─ module1.py
└─ module2.py

There are three ways to collect modules:

  • Modules under a package directory are collected.
  • The nav section is extended vertically.

Example:

nav:
  - index.md
  - $api/package.*
  - other.md

will be converted into

nav:
  - index.md
  - package: api/package/README.md
  - module_1: api/package/module_1.md
  - module_2: api/package/module_2.md
  - other.md
  • Modules under a package directory and its subdirectories are collected, recursively.
  • The nav section is extended vertically in flat structure.
  • Optionally, a section title can be set, for example, API.

Example:

nav:
  - index.md
  - API: $api/package.**
  - other.md

will be converted into

nav:
  - index.md
  - API:
    - package: api/package/README.md
    - subpackage_1: api/package/subpackage_1/README.md
    - module_11: api/package/subpackage_1/module_11.md
    - module_21: api/package/subpackage_1/module_12.md
    - subpackage_2: api/package/subpackage_2/README.md
    - module_21: api/package/subpackage_2/module_21.md
    - module_22: api/package/subpackage_2/module_22.md
    - module_1: api/package/module_1.md
    - module_2: api/package/module_2.md
  - other.md
  • Modules under a package directory and its subdirectories are collected, recursively.
  • The nav section is extended to have the same tree structure as the package.
  • Optionally, a top section title can be set, for example, API.

Example:

nav:
  - index.md
  - API: $api/package.***
  - other.md

will be converted into

nav:
  - index.md
  - API:
    - package: api/package/README.md
      - subpackage_1:
        - subpackage_1: api/package/subpackage_1/README.md
        - module_11: api/package/subpackage_1/module_11.md
        - module_12: api/package/subpackage_1/module_12.md
      - subpackage_2:
        - subpackage_2: api/package/subpackage_2/README.md
        - module_21: api/package/subpackage_2/module_21.md
        - module_22: api/package/subpackage_2/module_22.md
    - module_1: api/package/module_1.md
    - module_2: api/package/module_2.md
  - other.md

Note

  • README.md is an index page for packages. It corresponds to __init__.py.
  • Section and page titles can be configured programatically. See Configuration.

Example API documentations

To demonstrate the Page mode, try some libraries. For example, MkAPI is tested using following libraries:

  • Schemdraw － "Schemdraw is a Python package for producing high-quality electrical circuit schematic diagrams."
  • Polars － "Polars is a blazingly fast DataFrame library for manipulating structured data."
  • Altair － "Vega-Altair is a declarative visualization library for Python."

Use the following nav section in your mkdocs.yml if you want to check the output of MkAPI.

mkdocs.yml
nav:
  - index.md
  - API: $api/mkapi.**  # API documentation of MkAPI itself
  - Schemdraw: $api/schemdraw.***
  - Polars: $api/polars.***
  - Altair: $api/altair.***