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.