Yet Another MkDocs Parser

Related tags

Documentationyamp
Overview

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.

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 = 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.

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"

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.

Owner
Max Halford
Data scientist @alan-eu. PhD in applied machine learning. Kaggle competition Master when it was cool. Online machine learning advocate. Blogging enthusiast.
Max Halford
A complete kickstart devcontainer repository for python3

A complete kickstart devcontainer repository for python3

Viktor Freiman 3 Dec 23, 2022
Python script to generate Vale linting rules from word usage guidance in the Red Hat Supplementary Style Guide

ssg-vale-rules-gen Python script to generate Vale linting rules from word usage guidance in the Red Hat Supplementary Style Guide. These rules are use

Vale at Red Hat 1 Jan 13, 2022
Pydantic model generator for easy conversion of JSON, OpenAPI, JSON Schema, and YAML data sources.

datamodel-code-generator This code generator creates pydantic model from an openapi file and others. Help See documentation for more details. Supporte

Koudai Aono 1.3k Dec 29, 2022
OpenAPI (f.k.a Swagger) Specification code generator. Supports C#, PowerShell, Go, Java, Node.js, TypeScript, Python

AutoRest The AutoRest tool generates client libraries for accessing RESTful web services. Input to AutoRest is a spec that describes the REST API usin

Microsoft Azure 4.1k Jan 06, 2023
MkDocs plugin for setting revision date from git per markdown file

mkdocs-git-revision-date-plugin MkDocs plugin that displays the last revision date of the current page of the documentation based on Git. The revision

Terry Zhao 48 Jan 06, 2023
Python For Finance Cookbook - Code Repository

Python For Finance Cookbook - Code Repository

Packt 544 Dec 25, 2022
Test utility for validating OpenAPI documentation

DRF OpenAPI Tester This is a test utility to validate DRF Test Responses against OpenAPI 2 and 3 schema. It has built-in support for: OpenAPI 2/3 yaml

snok 106 Jan 05, 2023
Poetry plugin to export the dependencies to various formats

Poetry export plugin This package is a plugin that allows the export of locked packages to various formats. Note: For now, only the requirements.txt f

Poetry 90 Jan 05, 2023
A Sublime Text plugin to select a default syntax dialect

Default Syntax Chooser This Sublime Text 4 plugin provides the set_default_syntax_dialect command. This command manipulates a syntax file (e.g.: SQL.s

3 Jan 14, 2022
My solutions to the Advent of Code 2021 problems in Go and Python 🎄

🎄 Advent of Code 2021 🎄 Summary Advent of Code is an annual Advent calendar of programming puzzles. This year I am doing it in Go and Python. Runnin

Orfeas Antoniou 16 Jun 16, 2022
A Json Schema Generator

JSON Schema Generator Author : Eru Michael About A Json Schema Generator. This is a generic program that: Reads a JSON file similar to what's present

1 Nov 10, 2021
This repo provides a package to automatically select a random seed based on ancient Chinese Xuanxue

🤞 Random Luck Deep learning is acturally the alchemy. This repo provides a package to automatically select a random seed based on ancient Chinese Xua

Tong Zhu(朱桐) 33 Jan 03, 2023
Sphinx Bootstrap Theme

Sphinx Bootstrap Theme This Sphinx theme integrates the Bootstrap CSS / JavaScript framework with various layout options, hierarchical menu navigation

Ryan Roemer 584 Nov 16, 2022
🌱 Complete API wrapper of Seedr.cc

Python API Wrapper of Seedr.cc Table of Contents Installation How I got the API endpoints? Start Guide Getting Token Logging with Username and Passwor

Hemanta Pokharel 43 Dec 26, 2022
A module filled with many useful functions and modules in various subjects.

Usefulpy Check out the Usefulpy site Usefulpy site is not always up to date Download and Import download and install with with pip download usefulpyth

Austin Garcia 1 Dec 28, 2021
Contains the assignments from the course Building a Modern Computer from First Principles: From Nand to Tetris.

Contains the assignments from the course Building a Modern Computer from First Principles: From Nand to Tetris.

Matheus Rodrigues 1 Jan 20, 2022
Generate a single PDF file from MkDocs repository.

PDF Generate Plugin for MkDocs This plugin will generate a single PDF file from your MkDocs repository. This plugin is inspired by MkDocs PDF Export P

198 Jan 03, 2023
Types that make coding in Python quick and safe.

Type[T] Types that make coding in Python quick and safe. Type[T] works best with Python 3.6 or later. Prior to 3.6, object types must use comment type

Contains 17 Aug 01, 2022
Service for visualisation of high dimensional for hydrosphere

hydro-visualization Service for visualization of high dimensional for hydrosphere DEPENDENCIES DEBUG_ENV = bool(os.getenv("DEBUG_ENV", False)) APP_POR

hydrosphere.io 1 Nov 12, 2021