Generating pydantic documentation with autosummary

[bdhammel]

Thank you for creating this library!

I'm struggling a bit with the instructions to get "autodoc_pydantic" and "autosummary" to play nicely together. I was hoping you could clarify the instructions and warning on this page: https://autodoc-pydantic.readthedocs.io/en/stable/users/usage.html

As a sphinx noob, I'm not sure how to use "autodoc_pydantic’s autodocumenters ... to render the object’s documentation in the generated stub pages of autosummary."

My set up is:

---

.
├── build
│   ├── doctrees/
│   └── html/
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _apidoc/
    └── _templates/

where index.rst is:

Welcome to <my project> Documentation!
=======================================

.. autosummary::
   :toctree: _apidoc
   :template: custom-module-template.rst
   :recursive:

   <my project>

conf.py extensions are

extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.autodoc",  # Core Sphinx library for auto html doc generation from docstrings
    "sphinx.ext.autosummary",  # Create neat summary tables for modules/classes/methods etc
    "sphinx.ext.intersphinx",  # Link to other project's documentation (see mapping below)
    "sphinx.ext.viewcode",  # Add a link to the Python source code for classes, functions etc.
    "sphinx_autodoc_typehints",  # Automatically document param types (less noise in class signature)
    "IPython.sphinxext.ipython_console_highlighting",
    "sphinxcontrib.autodoc_pydantic",
    "sphinx.ext.coverage",
    "myst_parser",
]

and custom-module-template.rst is

{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: Module attributes

   .. autosummary::
      :toctree:
   {% for item in attributes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block functions %}
   {% if functions %}
   .. rubric:: {{ _('Functions') }}

   .. autosummary::
      :toctree:
      :nosignatures:
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block classes %}
   {% if classes %}
   .. rubric:: {{ _('Classes') }}

   .. autosummary::
      :toctree:
      :template: custom-class-template.rst
      :nosignatures:
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: {{ _('Exceptions') }}

   .. autosummary::
      :toctree:
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

{% block modules %}
{% if modules %}
.. autosummary::
   :toctree:
   :template: custom-module-template.rst
   :recursive:
{% for item in modules %}
   {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

From your warning, I understand that

The generated stub pages do not use the standard autosummary templates (e.g. the class template which lists all methods and attributes). As of sphinx version 3.5.4, this is not possible because autosummary does not support custom autodocumenters provided by extensions such as autodoc_pydantic

But I didn't fully understand what I need to modify to make them work?

my current workflow for generating the documentation is

rm -rf build
rm -rf source/_apidoc
sphinx-apidoc -o source/_apidoc ../<my project> --separate
make html

Where I was trying to use sphinx-apidoc to generate (what I believed to be) the stub pages.

Alternatively, I would just do

rm -rf build
rm -rf source/_apidoc
make html

And let autosummary generate everything, and _apidoc would be replaced with _autosummary in the above setup.

Thank you again for your work!

[daquinteroflex]

Did you manage to get this to work?

[bdhammel]

No, unfortunately not yet

[daquinteroflex]

I've got something that may help you. Not recursive but I a starting point to some level. See flexcompute/tidy3d#1270 (comment) within this branch https://github.com/daquinteroflex/autodoc_pydantic/tree/book_theme_template generates this website https://flexcompute-tidy3d-docs-demo.readthedocs-hosted.com/en/repo_merge_no_history/_autosummary/tidy3d.Simulation.html