sphinx-autoschematics

This is a Sphinx extension to automatically document Schematics models.

How to use it

In your Sphinx configuration you will need to list autoschematics as an extension:

extensions = ["autoschematics", "sphinx.ext.autodoc"]

This will provide a new automodel directive that you can provide the full path of a model to:

.. automodel:: myproject.models.MyModel

The extension will inspect your model and generate documentation from the docstring and the different fields on the model.

Example

Given the following model:

from schematics import types
from schematics.models import Model
from schematics.types import compound


class MyModel(Model):
    """MyModel defines the structure of data when interacting with SomeService

    Just like in Sphinx .rst files you can use restructured text directives in the
    docstring to provide rich content in the generated docs.

    .. code-block:: yaml

        foo: Foo
        bar:
          - bar1
          - bar2
    """

    foo = types.StringType(
        required=True,
        metadata=dict(
            custom_value=True
        )
    )

    bar = compound.ListType(types.StringType, default=list)

Would produce documentation like:

models.MyModel

MyModel defines the structure of data when interacting with SomeService

Just like in Sphinx .rst files you can use restructured text directives in the docstring to provide rich content in the generated docs.

foo: Foo
bar:
  - bar1
  - bar2

foo StringType()

Required: True

Default: Undefined

Custom value: True

bar ListType(StringType())

Required: False

Default: Undefined