Add config for builder independent TeX macro definitions

[chrisjsewell]

Originally posted by @chrisjsewell in https://github.com/executablebooks/jupyter-book/issues/909#issuecomment-680459818

Ok, so remembering how I implemented this now lol:

In the new myst-parser, with no changes to jupyter-book, you will need to add:

sphinx:
  config:
    myst_override_mathjax: false

I will make sure to document this in the myst-nb upgrade.

BUT, I think there could be a better solution than this, that I can look to implement in myst-parser.

There should be a separate myst_tex_macros configuration, which aims to work consistently across all builders, i.e. rather than having to set the Mathjax config (which is only relevant for HTML with mathjax) and adding a {math} block to enable rendering in TeX/PDF builds and/or adding LaTeX customisation. This config would add these automagically.

I'm suprised there is nothing like this already available in Sphinx, but I don't see anything?

[chrisjsewell]

cc @jstac @mmcky @najuzilu @phaustin, since I know you guys have worked with tex macros before

Does something like this make sense?

[mmcky]

@chrisjsewell based on working with sphinx in the past the two entry points for this type of config is:

HTML:

sphinx.ext.mathjax has a setting to set Tex Macros via mathjax_config -- but the inline configuration options link is currently broken. (Update: I think that link should be updated to https://docs.mathjax.org/en/v1.0/configuration.html#configuration-objects -- will submit a pr for Sphinx documentation)

LaTeX:

Would typically add \newcommand or \DeclareMathOperator into the latex_preamble

myst_tex_macros configuration, which aims to work consistently across all builders

Unifying over the builders would be nice via msyt_text_macros but the syntax for setting mathjax and working directly with latex varies. So we probably need to choose one entry format and convert the syntax for the other builder. (Update: Or come up with our own syntax for myst and convert to html and latex builder config)

I suspect we would specify mathjax config options (if it is not too limited an entry point) and then auto convert to latex and add it to the latex_preamble for the latex builder. However from reading about mathjax macros items like \DeclareMathOperator seem supported by not sure how they map to:

sphinx:
  config:
    mathjax_config:
      TeX:
        Macros:
          "N": "\\mathbb{N}"

which seems to translate to \newcommand\N{\mathbb{N}

[mmcky]

Note to @mmcky: Many forums suggest that \DeclareMathOperator should be recast into a Tex Macro using \operatorname