How do I modify the Sphinx js_files ordering?

[agoose77]

sphinxcontrib.mermaid adds¹ a JS file that conflicted with requirejs. I need to be able to change the order of extension loading to prevent this conflict, but this is controlled by Jupyter Book. Another approach is to manually re-order the added JS files, or modify the IPyWidgets configuration to change the JS priority.

Of all of these options, it looks like the easiest will be to try and modify the priority of the loaded JS files.

How can I ask Sphinx to run my code to change order of the JS files?

Footnotes

1. This is no longer the case, but this Discussion is a case-study ↩

[agoose77]

The easiest way to do this is to write a local Sphinx extension. This can be a single Python file, e.g. test_extension.py.

test_extension.py

def config_initialised(app, config):
    print(f"The current config is {config}")

def setup(app):
    app.connect('config-inited', config_initialised)

See https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events for more information on the Sphinx event system.

Then, we need to configure JupyterBook to load this extension:

_config.yml

sphinx:
  local_extensions: 
      test_extension: .

where . is the path to the directory containing test_extension.py

Right now this test app just prints the current configuration. We want to modify the JS file order. This can be done by changing the priority attribute of the JavaScript objects held in the html-content js_files list. So, first we need to get hold of this context. For that, we need the html-page-context event:

test_extension.py

def update_page_context(app, pagename, templatename, context, doctree):
    ...

def setup(app):
    app.connect('html-page-context', update_page_context)

Now we need to find our JS file, and tweak the ordering

test_extension.py

def update_page_context(app, pagename, templatename, context, doctree):   
    # Look for file
    for f in context['script_files']:
        if f.filename == "some-js-file.js":
            break
    else:
        return
    
    # Set new priority, lower is more important
    f.priority = 10 
    

def setup(app):
    app.connect('html-page-context', update_page_context)