In autosummary, expose complete objtype information to templates

[aeisenbarth]

Is your feature request related to a problem? Please describe. When using autodoc_pydantic with recursive autosummary, I must edit the template so that it documents items with objtype pydantic_model. The problem is that there is no way to properly select only this object type.

Templates have no access to objtype of an item. The only way to distinguish items by type is to use the variables available in templates, that sort items into some hand-crafted lists. However, this is unreliable because the provided variables don't cover every object type.

• object type data has no variable datas
• custom object types like pydantic_model cannot be selected separately. The approach of taking the rest (members minus all type lists) would combine objtype pydantic_model with data because both are in no existing list. But data cannot be handled as the same. See: https://github.com/mansenfranzen/autodoc_pydantic/issues/33#issuecomment-962894779

Describe the solution you'd like

It would be nice to have a more generalized approach.

I would like to propose:

• Drop the hard-coded lists functions, classes etc. in sphinx.ext.autosummary.generate:generate_autosummary_content but create dynamic lists for all objtypes found by the documenter. For each found type, add it as a key to ns and expose it to templates.
• Drop the all_… variables. Read all public items into a single public list. This is simpler and works better with the above generalization. Templates can combine both like {{ for item in classes if item in public }}.

Describe alternatives you've considered

Forking and copy-pasting the source code of autosummary as a custom sphinx extension (see: https://github.com/mansenfranzen/autodoc_pydantic/issues/33#issuecomment-1085211704) .

[bryevdv]

I would like to second this proposal. We were trying to evaluate autosummary for Bokeh but it currently seems like a non-starter. Bokeh has custom documenter classes like:

class ModelDocumenter(ClassDocumenter):
    directivetype = "bokeh-model"
    objtype = "model"
    priority = 20

    @classmethod
    def can_document_member(cls, member, membername, isattr, parent):
        return isinstance(member, type) and issubclass(member, Model)

but autosummary hard-codes the objtype values it collects:

https://github.com/sphinx-doc/sphinx/blob/6fd8b3004315f56b4464d9426829f7643e7b7bc1/sphinx/ext/autosummary/generate.py#L280-L281

so all of our Model classes are completely ignored in the generated docs since their objtype is not 'class'.

I had intended to ask about a way to specify additional objtypes (which seems like it would solve our problem) but simply providing all the objtype information as proposed above would also provide a path for us to create usable templates.

[bryevdv]

@aeisenbarth I see your existing PR is still marked as a draft. Did you intend to continue on this PR?

This seems like a relatively small change on the Sphinx side but it is currently blocking a major improvement we would like to make on our docs, so I am interested to try and help move it forward. cc @AA-Turner for any thoughts here about requirements from the Sphinx end of things.

[aeisenbarth]

The PR is functional but I considered it as a proof of concept and was waiting for feedback on my questions. Afterall, it is a major change and throws out the previous approach to template variables.

Would be great if someone could have a look!