Repository files navigation

sphinx-math-dollar is a Sphinx extension to let you write LaTeX math in RST using $$.

To enable install it

pip install sphinx-math-dollar

or

conda install -c conda-forge sphinx-math-dollar

Then in yourconf.py, add'sphinx_math_dollar' to your extensions list:

extensions= ['sphinx_math_dollar','sphinx.ext.mathjax']mathjax_config= {'tex2jax': {'inlineMath': [ ["\\(","\\)"] ],'displayMath': [["\\[","\\]"] ],    },}mathjax3_config= {"tex": {"inlineMath": [['\\(','\\)']],"displayMath": [["\\[","\\]"]],  }}

Themathjax_config is needed to prevent MathJax from parsing dollar signswhich are ignored by the extension because they should not be parsed as math.

You will now be able to use dollar signs for math, like$\int\sin(x)\,dx$,which will produce$intsin(x),dx$. You can also use double dollar signs fordisplay math, like$$\int\sin(x)\,dx$$, which produces$$intsin(x),dx$$(if you are reading this on GitHub, look at the version built by Sphinxhere). The usual Sphinx:math:and.. math:: directives will also continue to work.

The extension will also work with docstrings when combined with thesphinx.ext.autodocextension.

sphinx-math-dollar uses a blacklist to determine whichdocutils nodes should not beparsed. The default blacklist is

(FixedTextElement, literal, math)

FixedTextElement covers theSimple Body Elements nodes.

Any docutils node that is contained in a blacklisted node or a subclass of ablacklisted node will not have$math$ parsed as LaTeX.

You can modify this by settingmath_dollar_node_blacklist inconf.py.For example, to also prevent$math$ from rendering inheaders nodes, add

fromsphinx_math_dollarimportNODE_BLACKLISTfromdocutils.nodesimportheadermath_dollar_node_blacklist=NODE_BLACKLIST+ (header,)

Note that configuring this variable replaces the default, so it is recommendedto always include the above default values (NODE_BLACKLIST) in addition toadditional nodes.

To debug which nodes are skipped, set the environment variableMATH_DOLLAR_DEBUG=1 or setmath_dollar_debug = True inconf.py.

If you feel a node should always be part of the default blacklist, please makeapull request.

Seethe issue trackerfor a full list of known issues.

• Absolute values can produce errors likeInline substitution_referencestart-string without end-string.. Seeissue #16.

  This is because Sphinx parses the vertical bars|x| as inlinesubstitutions. To work around this, add spaces around the absolute valuebars, like1 + | x | + y. If an absolute value bar is at the beginningor end of the math expression, use curly braces (to avoid false positives,sphinx-math-dollar will not parse dollar signs as math if there is a spaceafter the first$ or before the last$). For example, replace$|y|\geq |x^e|$ with${ | y | \geq | x^e | }$, which produces${ | y |geq | x^e | }$.

sphinx-math-dollar is designed to work with RST, which does not nativelysupport dollar signs for LaTeX math. If you prefer Markdown, we recommendusing [MyST](https://myst-parser.readthedocs.io/en/latest/), which nativelysupports dollar math (this extension is not required).

MIT.