sphinx-pydantic¶
Autogenerate documentation from pydantic objects in Sphinx
Introduction¶
Sphinx-pydantic generates schema documentation from pydantic models. For example,
from pydantic import BaseModel, Field
class Thing(BaseModel):
"""
An example of a pydantic object from which we
can autogenerate schema documentation.
"""
name: str = Field(
...,
title='name',
description='Name of this thing',
)
Thing¶
An example of a pydantic object from which we can autogenerate schema documentation. | ||
type | object | |
properties | ||
|
name | |
Name of this thing | ||
type | string |
How does it work?¶
Sphinx-pydantic is an Sphinx extension that provides a new directive for adding a pydantic objects to your page and leverages sphinx-jsonschema to generate schema tables.
Add sphinx-pydantic
to the extensions in your Sphinx conf.py
file.
# conf.py
...
extensions = [
...,
'sphinx-pydantic',
]
and you can use the pydantic
directive in your .rst
docs.
some text ...
.. pydantic:: thing.Thing
some more text ...
thing.Thing
is a class (in the thing
module) that subclasses pydantic.BaseModel
.
Sphinx-pydantic imports this class and generates schema using pydantic’s sweet API.
By default sphinx is calling the schema_json function from pydantic BaseModel.
You can customize the displayed schema by implementing a schema_rst function inside your class,
which then will be called instead without any arguments.