Equation numbers in manual

[johnomotani]

It would be nice to have equation numbers shown in the manual on readthedocs.io, in particular for the 'Field-aligned coordinates' section. I'm not a reStructuredText expert does anyone know if there's an easy way to do this? A few equation numbers seem to be shown, I think it might be when there's a reference to them somewhere else, but it would be nice for all of them to be numbered for when we want to refer to them in an external document, email, etc.

[ZedThree]

Sphinx numbers them iff they have a :label:: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#math, so this

.. math::
   :label: eq:coordtransform

   \begin{aligned}
   x = {\sigma_{B\text{pol}}}\left(\psi - \psi_0\right) \qquad y = \theta \qquad z = \sigma_{B\text{pol}}
   \left(\phi - \int_{\theta_0}^{\theta}\nu\left(\psi,\theta\right)d\theta\right)
   \end{aligned}

gets a number: https://bout-dev.readthedocs.io/en/latest/user_docs/coordinates.html#equation-eq-coordtransform

(Although the number appears before the equation for me... might need some CSS trickery)

But there are some options for MathJax, which might help: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax

Playing about with the MathJax, it seems it can autonumber the equations, but then we don't get the ability to reference them nicely. But then if we use :label: to get the nice referencing, we can't turn off the numbering/use the MathJax number in the reference.

It looks like manually adding :label: might be the best option (and/or submit an enhancement request to Sphinx)

[johnomotani]

Thanks @ZedThree! The current labels look weird to me too (above the equation and centred).

[johnomotani]

Not sure it's a sphinx issue though - when I build the html docs on my laptop, the equation numbers look nice (placed to the right of the equations).

[johnomotani]

OK, I'm labelling the equations. PR soon...

[johnomotani]

I've posted a StackOverflow question about the equation number positioning, because that was where the readthedocs support page suggested https://stackoverflow.com/questions/67065252/how-to-put-equation-numbers-on-the-right-on-readthedocs