3

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(...)

  1. 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
  2. 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 per autodoc_type_aliases = {...} and python_use_unqualified_type_names = True config options. note that it also doesn't work for python internal types like re.Pattern.

I've tried

  • (1) various combinations of ..currentmodule:: in the index.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.

Philipp Stephan
  • 372
  • 5
  • 17
  • See the last sentence in my answer here: https://stackoverflow.com/questions/52395174/shorter-name-for-the-class-link-in-sphinx/52395525#52395525 – Steve Piercy Apr 04 '23 at 08:46

0 Answers0