sphinx-doc / sphinx-doc/sphinx

autosummary: event for dynamic context

Open
#11,342 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

As far as I can tell, there currently is no easy way to get additional dynamic context in autosummary templates, based on the element being processed.

If you require a specific example, I want to generate method and property autosummaries that also list all base classes where they are implemented.

For static data, there is autosummary_context, which is added to the context before the template is rendered. Just after that, I propose to emit a new event, autosummary-context. Callbacks to this event should be able to provide dynamic context based on the name, obj, parent, and static context being processed.

This can be achieved by a small addition along these lines after sphinx/ext/autosummary/generate.py:475:

         context: dict[str, Any] = {}
         if app:
             context.update(app.config.autosummary_context)
+            results = app.emit('autosummary-context', name, obj, parent, context)
+            for extra_context in results:
+                if extra_context:
+                    context.update(extra_context) 

         content = generate_autosummary_content(name, obj, parent, template, entry.template,
                                                imported_members, app, entry.recursive, context,
                                                modname, qualname)

It would also require the new event to be registered in the extension's setup() function, but no further changes.

The only alternative I can see is creating a custom extension based on autosummary.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at sphinx/ext/autosummary/generate.py around line 475 and inspect the extension's setup() function for event registration. Confirm how autosummary_context is prepared and how emitted callback results are handled. Done means the new autosummary-context event can provide dynamic context from name, obj, parent, and context for template rendering.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.