Add autodoc directive

Once you have followed the Installation Tutorial, then sphinx.ext.autodoc will call sphinx-apischema for every automodule, autoclass, automethod and autofunction it finds.

Example code

The following code is distributed as sphinx_apischema.example:

from dataclasses import dataclass
from typing import Type, TypeVar

from apischema import schema
from typing_extensions import Annotated as A

# Maximum age we support for an object
_MAX_AGE = 1000.0

#: TypeVar representing MyClass or a subclass of it
Cls = TypeVar("Cls", bound="MyClass")

# Used below whenever we have a name argument
AName = A[str, schema(description="The name of the object")]


@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: AName
    age: A[float, schema(description="How old it is", min=0.0, max=_MAX_AGE)] = 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}"

    @classmethod
    def old(cls: Type[Cls], name: AName) -> Cls:
        """Return an old object"""
        return cls(name, age=100)

    @staticmethod
    def oldest() -> float:
        """Return the maximum age we support for an object"""
        return _MAX_AGE


def say_hello(name: AName) -> str:
    """Return a polite greeting"""
    return f"Hello {name}"

The directive

You can add documentation for it to your sphinx project by placing the following directive in any rst file:

.. automodule:: sphinx_apischema.example
    :members:

This will generate the following documentation in your output HTML:

sphinx_apischema.example.Cls

TypeVar representing MyClass or a subclass of it

alias of TypeVar(‘Cls’, bound=MyClass)

class sphinx_apischema.example.MyClass(name, age=5)

Holds some very useful information about an object.

Parameters

• name (str) – The name of the object

• age (float) – How old it is - minimum: 0.0, maximum: 1000.0

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

summary(hide_age=True) → str

Return a nicely formatted summary of the object

Parameters

hide_age (bool) – Be secretive about the true age

classmethod old(name) → sphinx_apischema.example.Cls

Return an old object

Parameters

name (str) – The name of the object

static oldest() → float

Return the maximum age we support for an object

sphinx_apischema.example.say_hello(name) → str

Return a polite greeting

Parameters

name (str) – The name of the object