馃憣 Add CoreEvent
enum as argument for Sphinx.callback
#12259
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
When creating sphinx extensions (or looking at existing ones), it is always a source of annoyance/confusion trying to remember what callback events are available, what their purpose is, and also what their signatures should be.
Here I add the
sphinx.events.CoreEvent
enum, and allow this to be passed toSphinx.connect
, as an alternative to astr
name.This makes it easier to write and introspect extensions, and also more type safe.
I could also add
@overload
functions to theEventManager.callback
, with specific function signatures for each of the items,but I will wait to get feedback first.
It would also be interesting to consider using this to "auto-generate" some of https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events, but that is likely beyond the scope of this PR.
(I am definitely a fan of co-locating API documentation close to where it is implemented 馃槃 )