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. As an example, it's used to produce the documentation for River.
- Docstring inheritance — methods inherit docstrings from their parent(s)
- Type annotation friendly — no need to specify parameter types in docstrings if they're already type annotated
- Automatic linking — class and function mentions are automatically replaced with a link
- Pretty doctests —
>>>and...are automatically removed from doctests
You should be able to use this with any Python version above or equal to 3.8.
pip install git+https://github.com/MaxHalford/yampInstalling 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 docsThis 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.
As a general rule, the docstrings are expected to follow 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 types should not be documented. Instead, they are deduced from the type hints.
❌ Bad
class Animal:
"""
Parameters
----------
name: str
The animal's name.
"""
def __init__(self, name):
self.name = name✅ Good
class Animal:
"""
Parameters
----------
name
The animal's name.
"""
def __init__(self, name: str):
self.name = nameIf 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.
❌ Bad
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"✅ Good
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"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
pytestThis project is free and open-source software licensed under the MIT license.