I am using Sphinx with autodoc and autosummary to generate documentation for a pydantic model using autodoc_pydantic.
The model is quite complex and has a lot of sub-models in various files and includes custom types used for validation in a separate file. It is also part of a larger package, but I only want to document this module.
mypackage/
__init__.py
model/
__init__.py
model.py
submodel.py
types.py
model_doc/
_build/
_autosummary/
conf.py
index.rst
So model.py
could look something like this:
from pydantic import BaseModel
from types import Language
# #: Supported languages
# Language = Literal['de', 'en']
from .submodel import SubModel
class Model(BaseModel):
#: The language
language: Language = 'en'
#: submodel settings
submodel: SubModel = SubModel()
I also from .model import Model
in __init__.py
.
Now I have the follwing settings set in model_doc/conf.py
sys.path.insert(0, os.path.abspath('..'))
import mypackage
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.intersphinx',
'sphinxcontrib.autodoc_pydantic',
]
add_module_names = False
python_use_unqualified_type_names = True
autosummary_generate = True
autoclass_content = 'class'
autodoc_class_signature = 'separated'
autodoc_inherit_docstrings = False
autodoc_default_options = {
'members': True,
'undoc-members': True,
'private-members': True,
}
autodoc_typehints_format = 'short'
autodoc_preserve_defaults = True
autodoc_type_aliases = {
'Pattern': 're.Pattern',
'Language': 'mypackage.model.types.Language',
}
I render with the simple index.rst
of
.. autosummary::
:toctree: _autosummary
:recursive:
mypackage.model
But neither add_omdule_names
nor python_use_qualified_type_names
has any effect. I think it has to do with autodoc_pydantic
, which seems non-trivial, as pydantic messes with meta classes and the like, so just regular .. automodule::
was not working the the default values and produced strange private member artifacts.
In the sidebar of the rendered docs I get
mypackage.model
mypackage.model.model
mypackage.model.Model.language
mypackage.model.Model.submodel
mypackage.model.submodel
mypackage.model.types
and the page renders roughly like
mypackage.model.model
pydantic model
Model
field
language
:mypackage.model.types.Language
= 'en'field
submodel
:SubModel
=SubModel(...)
- the sidebar and the page heading should only show the module or class name not the full path including the package. as per
add_module_names = False
, but it's not working SubModel
links correctly to the rendered page for that class, whereas the type should be displayed without the module path and should also link to the correct page. as perautodoc_type_aliases = {...}
andpython_use_unqualified_type_names = True
config options. note that it also doesn't work for python internal types likere.Pattern
.
I've tried
- (1) various combinations of
..currentmodule::
in theindex.rst
, which didn't help - (1) setting
autosummary_generate = False
temporarily and manually inserting.. currentmodule::
directives into the stub pages, which didn't work - (2) adding
from __future__ import annotations
to all source files, which did't help
I would appreciate any suggestions on these two problems.