Esbonio overwrites results of other source-read event listeners

[Stefan Schulz]

I'm currently working on a project where we register an extension to Sphinx' source-read event, in order to modify the documentation.
This works fine when we use sphinx-build, but fails when using esbonio.
It looks like esbonio registers its own listener to the source-read event to enable the live preview feature:

def cb_source_read(self, app, docname, source):
    """Callback handling source_read event."""


    if not self.user_config.server.enable_live_preview:  # type: ignore
        return


    filepath = app.env.doc2path(docname, base=True)
    uri = Uri.from_fs_path(filepath)


    doc = self.workspace.get_document(uri)
    source[0] = doc.source

However, since this listener is registered using the default priority (500), it seems to overwrite the results provided by our own extension.

Would it be possible to register the esbonio listener at a higher priority (499 and below), so that other extensions may modify the code further without having to increase their own priority?

[Nirmal Sasidharan]

@Rubyfi Thanks for the finding.
You are right it makes sense to provide a much lower priortity such that other extensions can plugin in? How about 490?
@aniketsalve22 Do you see an issue here? Else can you please raise a PR?

[Alex Carney]

Can anyone think of a use case where a Sphinx extension would want it's event handler to run before esbonio's? I can't think of any... especially considering it wipes out any existing content (by design).
I'm wondering if the handler should be registered with a priority of 0 so that it is always run first.

That way running under esbonio vs sphinx-build should be invisible to any extension (in this case at least)

[Stefan Schulz]

Can anyone think of a use case where a Sphinx extension would want it's event handler to run before esbonio's? I can't think of any... especially considering it wipes out any existing content (by design). I'm wondering if the handler should be registered with a priority of 0 so that it is always run first.

That way running under esbonio vs sphinx-build should be invisible to any extension (in this case at least)

The only use case I could think of are sphinx' own event listeners, but they're all registered using the standard priority as well:

• duration
• intersphinx

The only downside I can see right now is that the duration feature will not measure the time it takes to run the esbonio event listener correctly and attribute it to the init phase instead of the read phase.

[Alex Carney]

Thanks for digging those up - hadn't come across the duration extension before!

and attribute it to the init phase instead of the read phase

Part of me thinks that might even be the correct way to account for the time! 😄

Ultimately it's something we'll have to keep an eye on in case something changes in Sphinx that means setting priority to 0 is no longer a good idea.

[Alex Carney]

v0.16.1 is out with the priority on esbonio's source-read handler set to 0. Let me know if you encounter any issues.