Add compatibility with Mathjax3

[Daltz333]

See https://frc-docs--639.org.readthedocs.build/en/639/docs/software/advanced-controls/state-space/state-space-intro.html#wpilib-s-linearsystemloop

[humitos]

What are you using to render that? Mathjax is the one that's currently supported. See https://sphinx-hoverxref.readthedocs.io/en/latest/usage.html#tooltip-with-mathjax

[Daltz333]

It is using mathjax

[Daltz333]

Additionally, write clicking on the latex in your example gives this

[Daltz333]

This is another picture of it showing that we do indeed use mathjax

[humitos]

Do you have hoverxref_mathjax set? See https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html#confval-hoverxref_mathjax

I didn't find that option in your repository: https://github.com/wpilibsuite/frc-docs/blob/master/source/conf.py#L61

[Daltz333]

Oh no. I do not. Can I ask why it's not enabled by default?

[humitos]

It's not enabled by default because it triggers some "javascript magic events" to re-render all the formulas in the page; which is not required if mathjax is not used.

If you are curios, see https://github.com/readthedocs/sphinx-hoverxref/blob/master/hoverxref/_static/js/hoverxref.js_t#L112 --I'm not proud of that code, but I didn't find a better way of doing it, 😄

Please, let me know if that worked for you and feel free to close the issue in that case.

[Daltz333]

This issue is still present. See the "state" and "inputs" term on this page https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/physics-sim.html

and confirmed mathjax for hoverxref is enabled.

https://github.com/wpilibsuite/frc-docs/blob/d320917fa10928dbdcb87b01f21e3f93187378d8/source/conf.py#L136

[Daltz333]

[humitos]

I guess this is happening because you are using a mathjax version different than the default one? https://github.com/wpilibsuite/frc-docs/blob/d320917fa10928dbdcb87b01f21e3f93187378d8/source/conf.py#L138

If you open the browser console, you will see that the hoverxref code that tries to render latex is being triggered, but it's not defined.

Uncaught TypeError: MathJax.Hub is undefined

So, I guess that Mathjax3 changed the API and hoverxref is not compatible with it.

[Daltz333]

Mathjax3 will be the default as of Sphinx 4 as it offers much better page loading times and other optimizations. It'd be great to see hoverxref move toward this. I'll rename the issue

[Daltz333]

Just wanted to bump this issue, as Sphinx 4 will be released within the next month per sphinx-doc/sphinx#8195

[Daltz333]

Another ding. Sphinx 4 will be releasing this month, and this extension will be broken with the now default Mathjax 3

[humitos]

@Daltz333 I'm following Sphinx releases closely. However, I haven't had the time to work on this issue. Would you like to do some research about the changes required and start a draft PR?

[Daltz333]

I will look into it.

[Daltz333]

I did a little bit of investigation. It seems an immediate issue is that MathJax3 uses promises rather than queue. There is a handy little converter https://mathjax.github.io/MathJax-demos-web/convert-configuration/convert-configuration.html that works on configuration objects, but not queue. I'm looking into it now.

[Daltz333]

I attempted to use typeset promise, but I was not able to get it to work

[humitos]

Sphinx 4 will be releasing this month, and this extension will be broken with the now default Mathjax 3

Just wanted to note here that Sphinx 4 includes a new feature that breaks some compatibility with this extension. See sphinx-doc/sphinx#9115

I think it would be good to mention these limitations in the sphinx-hoverxref's documentation somewhere.

Latest fully supported Sphinx version is <3.5