sphinx-apischema

Sphinx extension to autodoc for apischema annotated classes/functions

PyPI	pip install sphinx-apischema
Source code	https://github.com/dls-controls/sphinx-apischema
Documentation	https://dls-controls.github.io/sphinx-apischema
Changelog	https://github.com/dls-controls/sphinx-apischema/blob/master/CHANGELOG.rst

If you have a class that looks like this:

from dataclasses import dataclass
from apischema import schema
from typing_extensions import Annotated as A

@dataclass
class MyClass:
    """Holds some very useful information about an object.

    We might use this in a registry of all the objects we have
    """

    name: A[str, schema(description="The name of the object")]
    age: A[float, schema(description="How old it is", min=0.0, max=1000.0)] = 5

    def summary(
        self,
        hide_age: A[bool, schema(description="Be secretive about the true age")] = True,
    ) -> str:
        """Return a nicely formatted summary of the object"""
        age = "***" if hide_age else self.age
        return f"{self.name}: {age}"

Generates documenation that looks like this:

How the documentation is structured

Documentation is split into four categories, accessible from links in the side-bar.

Tutorials

Tutorials for installation, library and commandline usage. New users start here.

How-to Guides

Practical step-by-step guides for the more experienced user.

Explanations

Explanation of how the library works and why it works that way.

Reference

Technical reference material, for classes, methods, APIs, commands, and contributing to the project.

About the documentation

Why is the documentation structured this way?