Expose complete objtype information to autosummary templates

sphinx/ext/autosummary/generate.py

@@ -23,6 +23,7 @@
 import pydoc
 import re
 import sys
+from collections import defaultdict
 from os import path
 from typing import TYPE_CHECKING, Any, NamedTuple
 
@@ -274,24 +275,34 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         respect_module_all = not app.config.autosummary_ignore_module_all
         imported_members = imported_members or ('__all__' in dir(obj) and respect_module_all)
 
-        ns['functions'], ns['all_functions'] = \
-            _get_members(doc, app, obj, {'function'}, imported=imported_members)
-        ns['classes'], ns['all_classes'] = \
-            _get_members(doc, app, obj, {'class'}, imported=imported_members)
-        ns['exceptions'], ns['all_exceptions'] = \
-            _get_members(doc, app, obj, {'exception'}, imported=imported_members)
-        ns['attributes'], ns['all_attributes'] = \
-            _get_module_attrs(name, ns['members'])
+        members_by_obj_type = _get_members_by_objtype(doc, app, obj, imported=imported_members)
+        for objtype in app.registry.documenters:
+            ns[objtype] = members_by_obj_type.get(objtype, [])
+        # TODO: Clash between objtype "module" and variable for current module name,
+        #  defined below
+        attributes_public, ns['attribute'] = _get_module_attrs(name, ns['members'])
+        ns['public'] = (_get_public_members(doc, app, obj, imported=imported_members) +
+                        attributes_public)
+
+        # Define legacy variables for compatibility
+        ns['functions'] = [item for item in ns['function'] if item in ns['public']]
+        ns['all_functions'] = ns['function']
+        ns['classes'] = [item for item in ns['class'] if item in ns['public']]
+        ns['all_classes'] = ns['class']
+        ns['exceptions'] = [item for item in ns['exception'] if item in ns['public']]
+        ns['all_exceptions'] = ns['exception']
+        ns['attributes'] = [item for item in ns['attribute'] if item in ns['public']]
+        ns['all_attributes'] = ns['attribute']
+
         ispackage = hasattr(obj, '__path__')
         if ispackage and recursive:
             # Use members that are not modules as skip list, because it would then mean
             # that module was overwritten in the package namespace
-            skip = (
-                ns["all_functions"]
-                + ns["all_classes"]
-                + ns["all_exceptions"]
-                + ns["all_attributes"]
-            )
+            skip = [
+                item for objtype, items in members_by_obj_type.items()
+                if objtype != "module"
+                for item in items
+            ]
 
             # If respect_module_all and module has a __all__ attribute, first get
             # modules that were explicitly imported. Next, find the rest with the
@@ -410,6 +421,46 @@ def _get_members(doc: type[Documenter], app: Sphinx, obj: Any, types: set[str],
     return public, items
 
 
+def _get_members_by_objtype(doc: type[Documenter], app: Sphinx, obj: Any, *,
+                            imported: bool = True) -> dict[str, list[str]]:
+    items: dict[str, list[str]] = defaultdict(list)
+
+    all_members = _get_all_members(doc, app, obj)
+    for name, value in all_members.items():
+        documenter = get_documenter(app, value, obj)
+        objtype = documenter.objtype
+        # skip imported members if expected
+        if imported or getattr(value, '__module__', None) == obj.__name__:
+            skipped = _skip_member(app, value, name, documenter.objtype)
+            if skipped is True:
+                pass
+            items[objtype].append(name)
+    return dict(items)
+
+
+def _get_public_members(doc: type[Documenter], app: Sphinx, obj: Any, *,
+                        include_public: Set[str] = frozenset(),
+                        imported: bool = True) -> list[str]:
+    public = []
+
+    all_members = _get_all_members(doc, app, obj)
+    for name, value in all_members.items():
+        documenter = get_documenter(app, value, obj)
+        # skip imported members if expected
+        if imported or getattr(value, '__module__', None) == obj.__name__:
+            skipped = _skip_member(app, value, name, documenter.objtype)
+            if skipped is True:
+                pass
+            elif skipped is False:
+                # show the member forcedly
+                public.append(name)
+            else:
+                if name in include_public or not name.startswith('_'):
+                    # considers member as public
+                    public.append(name)
+    return public
+
+
 def _get_module_attrs(name: str, members: Any) -> tuple[list[str], list[str]]:
     """Find module attributes with docstrings."""
     attrs, public = [], []

tests/roots/test-ext-autosummary-pydantic/_templates/autosummary/module.rst

@@ -0,0 +1,84 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attribute %}
+   {% if attribute %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attribute %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block function %}
+   {% if function %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in function %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block class %}
+   {% if class %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in class %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block pydantic_model %}
+   {% if pydantic_model %}
+   .. rubric:: {{ _('Models') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in pydantic_model %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block pydantic_settings %}
+   {% if pydantic_settings %}
+   .. rubric:: {{ _('Settings') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in pydantic_settings %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exception %}
+   {% if exception %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exception %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: {{ _('Modules') }}
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

tests/roots/test-ext-autosummary-pydantic/autosummary_dummy_module_with_pydantic.py

@@ -0,0 +1,9 @@
+__all__ = [
+    "MyModel",
+]
+
+from pydantic import BaseModel
+
+
+class MyModel(BaseModel):
+    attr: str

tests/roots/test-ext-autosummary-pydantic/conf.py

@@ -0,0 +1,12 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions = ['sphinx.ext.autosummary', "sphinxcontrib.autodoc_pydantic"]
+autosummary_generate = True
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+templates_path = ["_templates"]

tests/roots/test-ext-autosummary-pydantic/index.rst

@@ -0,0 +1,8 @@
+test-ext-autosummary-pydantic
+=============================
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   autosummary_dummy_module_with_pydantic

tests/test_extensions/test_ext_autosummary.py

@@ -1,5 +1,6 @@
 """Test the autosummary extension."""
 
+import importlib.util
 import sys
 from io import StringIO
 from pathlib import Path
@@ -248,6 +249,42 @@ def test_autosummary_generate_content_for_module(app):
     assert context['objtype'] == 'module'
 
 
+@pytest.mark.sphinx(testroot='ext-autosummary')
+def test_autosummary_generate_content_for_module_by_objtype(app):
+    import autosummary_dummy_module
+    template = Mock()
+
+    generate_autosummary_content('autosummary_dummy_module', autosummary_dummy_module, None,
+                                 template, None, False, app, False, {})
+    assert template.render.call_args[0][0] == 'module'
+
+    context = template.render.call_args[0][1]
+
+    assert context['public'] == ['Exc', 'Foo', 'bar', 'CONSTANT1', 'qux', 'quuz', 'non_imported_member']
+    assert context['class'] == ['Foo', '_Baz']
+    assert context['function'] == ['_quux', 'bar']
+    assert context['exception'] == ['Exc', '_Exc']
+    assert context['attribute'] == ['CONSTANT1', 'qux', 'quuz', 'non_imported_member']
+    # TODO: Clash between objtype "module" and variable "module" (current module name)
+    assert context['module'] == 'autosummary_dummy_module'
+
+
+@pytest.mark.skipif(not importlib.util.find_spec("sphinxcontrib.autodoc_pydantic"), reason="Requires pydantic, autodoc-pydantic")
+@pytest.mark.sphinx(testroot='ext-autosummary-pydantic')
+def test_autosummary_generate_content_for_module_with_pydantic(app):
+    import autosummary_dummy_module_with_pydantic
+    template = Mock()
+
+    generate_autosummary_content('autosummary_dummy_module_with_pydantic', autosummary_dummy_module_with_pydantic, None,
+                                 template, None, False, app, False, {})
+    assert template.render.call_args[0][0] == 'module'
+
+    context = template.render.call_args[0][1]
+
+    assert context['pydantic_model'] == ['MyModel']
+    assert 'MyModel' not in context['class']
+
+
 @pytest.mark.sphinx(testroot='ext-autosummary')
 def test_autosummary_generate_content_for_module___all__(app):
     import autosummary_dummy_module