yamp
Motivation
You want to document your project. You make an effort and write docstrings. You try Sphinx. You think it sucks and it's slow -- I did. You now want to use (Material for) MkDocs. You realize it only does rendering and does not parse docstrings. You need some glue in between. This is it.
This is yamp: Yet Another MkDocs Parser. It's opinionated and makes decisions for you. It's what we use to produce the documentation for River.
Installation
You should be able to use this with any Python version above or equal to 3.8.
pip install git+https://github.com/MaxHalford/yamp
Usage
Installing yamp will give you access to it on the command-line. As an example, assuming you have River installed, you can do this:
yamp river --out docs/api
This will parse all the modules, classes, and docstrings and dump them in a format that MkDocs understands. Typically, you would run this before calling mkdocs build.
Naturally, you can run yamp -h to see what options are available.
Style guide
As a general rule, the docstrings are expected the numpydoc style guide. There are just a few extra rules to take into account.
For examples, you may look at River's source code and check the docstrings therein.
Parameter typing
Parameter types should not be documented. Instead, they are deduced from the type hints.
class Animal:
"""
Parameters
----------
name: str
The animal's name.
"""
def __init__(self, name):
self.name = name
class Animal:
"""
Parameters
----------
name
The animal's name.
"""
def __init__(self, name: str):
self.name = name
Type hints and docstrings are inherited
If you have a base class with a type hinted method, then you do not have to type hint the method of the child class. The type hints will be inherited. The same goes for docstrings. We found this very useful in River because we have a few base classes that are inherited many times. This saves us from having to copy/paste docstrings all over the place.
import abc
class Animal(abc.ABC):
@abc.abstractmethod
def sound(self) -> str:
"""Make some noise.
Returns
-------
The noise.
"""
class Dog(Animal):
def sound(self) -> str:
"""Make some noise.
Returns
-------
The noise.
"""
return "woof woof"
import abc
class Animal(abc.ABC):
@abc.abstractmethod
def sound(self) -> str:
"""Make some noise.
Returns
-------
The noise.
"""
class Dog(Animal):
def sound(self):
return "woof woof"
Alternatives
Development
git clone https://github.com/MaxHalford/yamp
cd yamp
python -m venv .env
source .env/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"
python setup.py develop
pytest
License
This project is free and open-source software licensed under the MIT license.
35 Dec 23, 2022
104 Dec 31, 2022
124 Jan 6, 2023
3.4k Dec 30, 2022
60 Nov 16, 2022
4 Dec 4, 2021
12 Aug 19, 2021
510 Jan 2, 2023
1k Jan 1, 2023
230 Nov 16, 2022
129 Dec 17, 2022
60 Sep 13, 2022
332 Dec 26, 2022
121 Jan 5, 2023
51 Dec 27, 2022
65 Dec 10, 2022
11 Nov 21, 2022
1.1k Dec 31, 2022
266 Dec 13, 2022
282 Dec 28, 2022
198 Jan 3, 2023
38 Feb 26, 2022
67 Jan 4, 2023
1.1k Jan 4, 2023
14 Sep 10, 2022
49 Jan 9, 2023