Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/daizutabi/mkapi
A plugin for MkDocs to generate API documentation
https://github.com/daizutabi/mkapi
api-documentation markdown mkdocs-plugin
Last synced: about 1 month ago
JSON representation
A plugin for MkDocs to generate API documentation
- Host: GitHub
- URL: https://github.com/daizutabi/mkapi
- Owner: daizutabi
- License: mit
- Created: 2020-04-19T07:43:40.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-07T22:27:35.000Z (6 months ago)
- Last Synced: 2024-07-18T18:54:15.502Z (2 months ago)
- Topics: api-documentation, markdown, mkdocs-plugin
- Language: Python
- Homepage: https://daizutabi.github.io/mkapi/
- Size: 7.6 MB
- Stars: 95
- Watchers: 2
- Forks: 19
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- jimsghstars - daizutabi/mkapi - A plugin for MkDocs to generate API documentation (Python)
README
# MkAPI
[![PyPI Version][pypi-v-image]][pypi-v-link]
[![Python Version][python-v-image]][python-v-link]
[![Build Status][GHAction-image]][GHAction-link]
[![Coverage Status][codecov-image]][codecov-link]
MkAPI is a plugin for [MkDocs](https://www.mkdocs.org/) to generate
API documentation for your Python project.
MkAPI supports two styles of docstrings:
[Google](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
and
[NumPy](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
See [Napoleon](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/)
documentation for details.
## Screenshots
### Schemdraw (package tree view & package summary)
### Polars (class documentation & link to source code)
### Altair (table of contents)
## Features
* **Type annotation**: If you write your function such as
`def func(x: int) -> str:`, you don't need write type(s)
in Parameters, Returns, or Yields section again.
You can override the type annotation in the corresponding docstring.
* **Object type inspection**: MkAPI plugin creates *class*,
*dataclass*, *function*, *method*, *property* prefix for each object.
* **Docstring inheritance**: Docstring of a subclass can inherit parameters
and attributes description from its superclasses.
* **Table of Contents**: Table of contents are inserted into the documentation
of each package, module, and class.
* **Bidirectional Link**: Bidirectional links are created between
documentation and source code.
## Installation
Install the MkAPI plugin using pip:
```bash
pip install mkapi
```
## Configuration
Add the following lines to `mkdocs.yml`:
```yaml
plugins:
- mkapi
```
## Usage
MkAPI provides two modes to generate API documentation:
Object mode and Page mode.
### Object Mode
To generate the API documentation in a Markdown source,
add three colons + object full name.
The object can be a function, class, attribute, or module.
```markdown
::: package.module.object
```
The Object mode is useful to embed an object documentation
in an arbitrary position of a Markdown source.
For more details, see [Object mode](https://daizutabi.github.io/mkapi/usage/object).
### Page Mode
Using the Page mode, you can construct a comprehensive API documentation
for your project.
You can get this powerful feature by just one line in `mkdocs.yml`:
```yaml
nav:
- index.md
- API: $api/package.***
```
For more details, see [Page mode](https://daizutabi.github.io/mkapi/usage/page/).
[pypi-v-image]: https://img.shields.io/pypi/v/mkapi.svg
[pypi-v-link]: https://pypi.org/project/mkapi/
[python-v-image]: https://img.shields.io/pypi/pyversions/mkapi.svg
[python-v-link]: https://pypi.org/project/mkapi
[GHAction-image]: https://github.com/daizutabi/mkapi/actions/workflows/ci.yml/badge.svg?branch=main&event=push
[GHAction-link]: https://github.com/daizutabi/mkapi/actions?query=event%3Apush+branch%3Amain
[codecov-image]: https://codecov.io/github/daizutabi/mkapi/coverage.svg?branch=main
[codecov-link]: https://codecov.io/github/daizutabi/mkapi?branch=main