Support for idiomatic dollar math

[jedbrown]

Is your feature request related to a problem? Please describe.

The dollarmath feature of MyST is huge for readability of math-intensive writing. The current rst2myst parse produces a direct translation that has similar verbosity to ReST.

Describe the solution you'd like

I'd like to have an option that enables inline $\pi$ and displayed

$$
e = mc^2
$$ (eqn:best)

This is the best equation {eq}`eqn:best`

We may be able to help with the implementation, but have a couple questions:

1. Since dollarmath is an optional feature, I'm curious how you would like this gated in the interface. I could see it being managed by new keys in directives.yml, though a new --myst-extensions dollarmath would be more convenient.
2. Any notes on preferred implementation strategy.

Cc: @DiffeoInvariant

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[chrisjsewell]

Heya, Do you mean that you would want the RST equation directive converted to dollarmath? Or what would've an example input text?

[jedbrown]

Convert RST :math: and :math:numref: to dollarmath.

[chrisjsewell]

in v0.2.0 :math:`a^2 + b^2 = c^2` is converted to $a^2 + b^2 = c^2$ (controlled by the --dollar-math/--no-dollar-math). I haven't yet added conversion of math directives

[jedbrown]

Cool! This is really helpful, but display math is currently being double-escaped. a.rst:

.. math::
   :label: poisson-ratio

   \begin{aligned}
   \lambda &= \frac{E \nu}{(1 + \nu)(1 - 2 \nu)} \\
   \mu &= \frac{E}{2(1 + \nu)}
   \end{aligned}.

rst2myst convert a.rst produces a.md:

```{math}
:label: poisson-ratio

\\begin\{aligned}
\\lambda &= \\frac{E \\nu}{(1 + \\nu)(1 - 2 \\nu)} \\\\
\\mu &= \\frac\{E}{2(1 + \\nu)}
\\end\{aligned}.

[chrisjsewell]

ok cheers, I'll have a look why that is

[chrisjsewell]

all done in v0.3.0 ;give it a go and let me know if there are any more issues 😄

[jedbrown]

Gorgeous, thank you! I notice one remaining quirk in how dollarmath is applied for display math without a label/spacing. The block

.. math::
   \bm\sigma = \lambda (\operatorname{trace} \bm\epsilon) \bm I_3 + 2 \mu \bm\epsilon,

becomes

```{math} \bm\sigma = \lambda (\operatorname{trace} \bm\epsilon) \bm I_3 + 2 \mu \bm\epsilon,

while those with intervening spaces are placed in `$$`, e.g.,
````rst
.. math::

   \bm\sigma = \lambda (\operatorname{trace} \bm\epsilon) \bm I_3 + 2 \mu \bm\epsilon,

becomes

$$
\bm\sigma = \lambda (\operatorname{trace} \bm\epsilon) \bm I_3 + 2 \mu \bm\epsilon,
$$

as I think is intended. I don't recall if the former syntax is KaTeX-specific. We've been using it over MathJax because it has produced better quality and more consistent results between our HTML and PDF output. And I can work around this easily enough as we migrate this project to MyST.

Compare the first and second cases below. ````console $ rst2myst convert index.rst index.rst -> index.md CONVERTED (extensions: ['dollarmath', 'colon_fence']) FINISHED ALL! (extensions: ['dollarmath', 'colon_fence']) $ rg -A5 'The constitutive law' index.* index.rst 122:The constitutive law (stress-strain relationship) is therefore given by its gradient, 123- 124-.. math:: 125- \bm\sigma = \lambda (\operatorname{trace} \bm\epsilon) \bm I_3 + 2 \mu \bm\epsilon, 126- 127-where :math:`\bm I_3` is the :math:`3 \times 3` identity matrix, the colon represents a double contraction (over both indices of :math:`\bm \epsilon`), and the Lamé parameters are given by -- 135:The constitutive law (stress-strain relationship) can also be written as 136- 137-.. math:: 138- :label: linear-stress-strain 139- 140- \bm{\sigma} = \mathsf{C} \!:\! \bm{\epsilon}. index.md 114:The constitutive law (stress-strain relationship) is therefore given by its gradient, 115- 116-```{math} \bm\sigma = \lambda (\operatorname{trace} \bm\epsilon) \bm I_3 + 2 \mu \bm\epsilon, 117-``` 118- 119-where $\bm I_3$ is the $3 \times 3$ identity matrix, the colon represents a double contraction (over both indices of $\bm \epsilon$), and the Lamé parameters are given by -- 124:The constitutive law (stress-strain relationship) can also be written as 125- 126-$$ 127-\bm{\sigma} = \mathsf{C} \!:\! \bm{\epsilon}. 128-$$ (linear-stress-strain) 129- ````

[chrisjsewell]

Yeh for some weird reason the math directive can have an argument, which is actually just part of the body: https://github.com/sphinx-doc/sphinx/blob/eda4b1cfc49cddfeb8d9ce3b0c495ebebb01fb6c/sphinx/directives/patches.py#L183

so I just have to append that to the body if there is one