👌 Add CoreEvent enum as argument for Sphinx.callback

[chrisjsewell]

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 to Sphinx.connect, as an alternative to a str name.
This makes it easier to write and introspect extensions, and also more type safe.

I could also add @overload functions to the EventManager.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 😄 )

[danieleades]

Yay typesafety!

[danieleades]

we could take this further and make the CoreEvent enum the preferred approach (without breaking existing code)

Suggested change

	def connect(self, name: str | CoreEvent, callback: Callable, priority: int) -> int:
	@deprecated(reason="...")
	@overload
	def connect(self, name: str, callback: Callable, priority: int) -> int: ...
	@overload
	def connect(self, name: CoreEvent, callback: Callable, priority: int) -> int: ...
	def connect(self, name: str | CoreEvent, callback: Callable, priority: int) -> int:

[picnixz]

The deprecated decorator is only a 3.13 feature :(

[picnixz]

(In addition, you still want to connect with your own events)

[picnixz]

I think it's fine but the issue is that people would need to import the events module if they want to use the enumeration. So you should put it in a standalone module to avoid possible circular imports.

On the other hand, you could instead use Literal strings maybe? it could probably help if you want overloads since enumerations + literals are not happy together sometimes (I had an issue with that but I don't remember whether it's fixed or not).