https://github.com/sympy/sphinx-math-dollar

Sphinx extension to let you write LaTeX math using $$
https://github.com/sympy/sphinx-math-dollar

Last synced: 3 days ago
JSON representation

Sphinx extension to let you write LaTeX math using $$

• Host: GitHub
• URL: https://github.com/sympy/sphinx-math-dollar
• Owner: sympy
• License: mit
• Created: 2019-09-13T18:12:13.000Z (about 5 years ago)
• Default Branch: master
• Last Pushed: 2024-01-31T02:56:11.000Z (10 months ago)
• Last Synced: 2024-10-29T15:25:40.577Z (14 days ago)
• Language: Python
• Homepage: https://www.sympy.org/sphinx-math-dollar/
• Size: 482 KB
• Stars: 33
• Watchers: 21
• Forks: 11
• Open Issues: 12
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
====================

 sphinx-math-dollar

====================

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

To enable install it

.. code::

   pip install sphinx-math-dollar

or

.. code::

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

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

.. code:: python

   extensions = ['sphinx_math_dollar', 'sphinx.ext.mathjax']

   mathjax_config = {

       'tex2jax': {

           'inlineMath': [ ["\\(","\\)"] ],

           'displayMath': [["\\[","\\]"] ],

       },

   }

   mathjax3_config = {

     "tex": {

       "inlineMath": [['\\(', '\\)']],

       "displayMath": [["\\[", "\\]"]],

     }

   }

The ``mathjax_config`` is needed to prevent MathJax from parsing dollar signs

which 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 $\int\sin(x)\,dx$. You can also use double dollar signs for

display math, like ``$$\int\sin(x)\,dx$$``, which produces $$\int\sin(x)\,dx$$

(if you are reading this on GitHub, look at the version built by Sphinx `here

`_). The usual Sphinx ``:math:``

and ``.. math::`` directives will also continue to work.

The extension will also work with docstrings when combined with the

`sphinx.ext.autodoc

`_

extension.

Configuration

=============

sphinx-math-dollar uses a blacklist to determine which `docutils nodes

`_ should not be

parsed. The default blacklist is

.. code::

   (FixedTextElement, literal, math)

``FixedTextElement`` covers the `Simple Body Elements

`_ nodes.

Any docutils node that is contained in a blacklisted node or a subclass of a

blacklisted node will not have ``$math$`` parsed as LaTeX.

You can modify this by setting ``math_dollar_node_blacklist`` in ``conf.py``.

For example, to also prevent ``$math$`` from rendering in `headers nodes

`_, add

.. code:: python

   from sphinx_math_dollar import NODE_BLACKLIST

   from docutils.nodes import header

   math_dollar_node_blacklist = NODE_BLACKLIST + (header,)

Note that configuring this variable replaces the default, so it is recommended

to always include the above default values (``NODE_BLACKLIST``) in addition to

additional nodes.

To debug which nodes are skipped, set the environment variable

``MATH_DOLLAR_DEBUG=1`` or set ``math_dollar_debug = True`` in ``conf.py``.

If you feel a node should always be part of the default blacklist, please make

a `pull request `_.

Known Issues

============

See `the issue tracker `__

for a full list of known issues.

- Absolute values can produce errors like ``Inline substitution_reference

  start-string without end-string.``. See `issue #16

  `__.

  This is because Sphinx parses the vertical bars ``|x|`` as inline

  substitutions. To work around this, add spaces around the absolute value

  bars, like ``1 + | x | + y``. If an absolute value bar is at the beginning

  or 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 space

  after the first ``$`` or before the last ``$``). For example, replace ``$|y|

  \geq |x^e|$`` with ``${ | y | \geq | x^e | }$``, which produces ${ | y |

  \geq | x^e | }$.

Markdown

========

sphinx-math-dollar is designed to work with RST, which does not natively

support dollar signs for LaTeX math. If you prefer Markdown, we recommend

using [MyST](https://myst-parser.readthedocs.io/en/latest/), which natively

supports dollar math (this extension is not required).

License

=======

MIT.