Repository: pypa/readme_renderer (language: python)

Issue:
Docutils settings make math rendering fail in Docutils 0.14+
Starting in Docutils 0.14, a warning is emitted if [`math_output`](https://docutils.sourceforge.io/docs/user/config.html#math-output) is set to `"MathJax"` without a URL to a MathJax library appended.  `readme_renderer` currently sets `math_output` to just `"MathJax"` and also sets `halt_level` to 2 (WARNING), meaning that, if an input document uses either the `:math:` role or `math::` directive, a warning is emitted, and then that warning causes the rendering to fail.  If your intention is to support math input, you should either append something to the `math_output` setting (it doesn't matter what, as you don't use the relevent part of the rendered document) or else change the setting to something other than MathJax.  (Note that Warehouse also currently doesn't seem to load any MathJax libraries; perhaps that's worth an issue over there.)


Discussion / hints:
I don't think we've ever supported the math directive on PyPI. If this is suddenly causing failures we should remove it entirely until we're prepared to fully support it.

Fully supporting the math directive is captured in https://github.com/pypa/readme_renderer/issues/115.

Fix patch:
diff --git a/readme_renderer/rst.py b/readme_renderer/rst.py
index cadd843..fdc4e82 100644
--- a/readme_renderer/rst.py
+++ b/readme_renderer/rst.py
@@ -76,7 +76,8 @@ def emptytag(
 
     # Output math blocks as LaTeX that can be interpreted by MathJax for
     # a prettier display of Math formulas.
-    "math_output": "MathJax",
+    # Pass a dummy path to supress docutils warning and emit HTML.
+    "math_output": "MathJax /dummy.js",
 
     # Disable raw html as enabling it is a security risk, we do not want
     # people to be able to include any old HTML in the final output.


Test patch:
diff --git a/tests/fixtures/test_rst_math.html b/tests/fixtures/test_rst_math.html
new file mode 100644
index 0000000..763c958
--- /dev/null
+++ b/tests/fixtures/test_rst_math.html
@@ -0,0 +1,8 @@
+<p>A <tt>math</tt> directive:</p>
+<div class="math">
+\begin{equation*}
+\alpha _t(i) = P(O_1, O_2, \ldots  O_t, q_t = S_i \lambda )
+\end{equation*}
+</div>
+<p>A <tt>:math:</tt> role:</p>
+<p>The area of a circle is <span class="math">\(A_\text{c} = (\pi/4) d^2\)</span>.</p>
diff --git a/tests/fixtures/test_rst_math.rst b/tests/fixtures/test_rst_math.rst
new file mode 100644
index 0000000..b4e6db7
--- /dev/null
+++ b/tests/fixtures/test_rst_math.rst
@@ -0,0 +1,14 @@
+.. Sample from https://docutils.sourceforge.io/docs/ref/rst/directives.html#math
+
+A ``math`` directive:
+
+.. math::
+
+  α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
+
+
+.. Sample from https://docutils.sourceforge.io/docs/ref/rst/roles.html#math
+
+A ``:math:`` role:
+
+The area of a circle is :math:`A_\text{c} = (\pi/4) d^2`.