sphinx-doc / sphinx-doc/sphinx
autosummary: event for dynamic context
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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