Latex equation broken in RZZGate documentation

[aeddins-ibm]

Environment

Online docs

What is happening?

On the RZZGate docs page: https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.RZZGate

An equation that is a helpful reference for getting factors of 2 correct does not render. Mousing over gives the tooltip shown with the error message suggesting to use renewcommand instead of newcommand:

How can we reproduce the issue?

https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.RZZGate

What should happen?

Equation should render without an error

Any suggestions?

May just need to replace \newcommand with \renewcommand

[aeddins-ibm]

This seems to affect other pages as well, such as https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.RXGate

Maybe worth searching the repo for all uses of \newcommand ?

[jakelishman]

This sounds suspiciously like the KaTeX setup for the markdown components of the new Qiskit/documentation is defining the \th macro in its preamble, which we never used to do when we hosted the docs from this repo (hence the new errors). Let me move this issue over there for now, though it might be that we end up moving it back here and removing the \newcommand stuff.

(Personally I'm not convinced that it's a great idea to use a macro like this in simple definitions, but I know I write LaTeX differently to a lot of people.)

[jakelishman]

Oh, come to think of it, I think the Sphinx build used MathJax as its backend when it lived in Terra, but it's now clearly using KaTeX. KaTeX includes a \th command in its default preamble, so it looks like we're going to have to change this from the Terra side after all, so I'll transfer it back.

This is one place where the docs-build split is potentially going to cause nuisances, though - the MathJax parsing and rendering engine supports a totally different set of features to KaTeX (imo KaTeX is better).

We shouldn't really \renewcommand, because that'll be a bit fragile if we ever change the rendering engine. I think it'll be safest to remove the macro definitions and just inline the \frac\theta2 stuff. Personally I don't even think a displayed fraction is even the best typographic choice when it's up in an exponential superscript (so imo a bunch of the uses of \th macros should really be e^{-i \theta/2} ($e^{-i \theta/2}$) instead of e^{-i \frac\theta2} ($e^{-i\frac\theta2}$)).