Expose complete objtype information to autosummary templates

[aeisenbarth]

Subject: Create autosummary template variables dynamically based on objtype from documenters, enabling custom object types like pydantic_model to be selectable in templates (#12021, mansenfranzen/autodoc_pydantic#33).

Feature or Bugfix

• Feature
• Bugfix
• Refactoring

Purpose

The templates and template variables in autosummary expose only a hard-coded set of object types like (classes for object type class) and the templates.

As a consequence, it is not possible to add custom sections for custom object types to the template, because one can not select/distinguish the custom type from the available types. Custom object types are provided for example by autodoc-pydantic. It works only with one level of autosummary which then uses the base template with directive .. auto{{ objtype }}:: (with objtype = pydantic_model). However, this is not possible with :recursive: because then the module template is used which contains no section for the custom type.

The current recommendation is to fork autosummary (mansenfranzen/autodoc_pydantic#33 (comment)).

Detail

This PR aims to avoid forking and proposes different template variables. I do not request to merge this, but it is a basis for discussion.

Changes:

• Members are grouped by objtype and exposed as variables with exactly that object type. This makes the implementation more generic and open to new object types, but also drops repetitive code.
• Old variable names are still kept for backward-compatibility, although the naming is overlapping and can create confusion.
• The branch contains a test case for pydantic-autodoc just for illustration. I did not add pydantic to dependencies. Also there is hopefully a better way to register and test a custom object type.

Questions:

• Naming: Object types are singular, that means "classes" is now "class".
  • On one side, this is consistent with objtype.
  • On the other side, it is unintuitive since the variables are lists of many items (plural).
  • I tested that "class" does not cause an error in jinja due to reserved word.
  • "module" clashes, since that already refers to the current module, not to the list of contained members of module type.
  • Possibly we could avoid name clashes by adding a plural suffix "s" (although then it does not match exactly the objtype), or prefixing members_{objtype}.
• Testing: What is the simplest way to create a custom objtype only for the purpose of a test, so I can remove pydantic from the test test_autosummary_generate_content_for_module_with_pydantic?

Relates

• In autosummary, expose complete objtype information to templates #12021