Clarify MathJax extension usage

- We recently hit an issue where we expected the MathJax extension to
  work with the default MathJax markup.  Obviously that shouldn't be
  the case (since then other formats couldn't use the math), but it
  can't hurt to include a hint.
- Link from the math HTML extension page to the relevant
  roles/directives.
- Also make it explicit that MathJax has a default, and that it's an
  external resource that will be dynamically linked.
This commit is contained in:
Richard Darst 2019-03-27 17:43:51 +02:00
parent e1185ff2e4
commit dd0246c6dc

View File

@ -15,7 +15,8 @@ Math support for HTML outputs in Sphinx
So mathbase extension is no longer needed.
Since mathematical notation isn't natively supported by HTML in any way, Sphinx
gives a math support to HTML document with several extensions.
gives a math support to HTML document with several extensions. These use the
Sphinx :rst:dir:`directives <math>` and :rst:role:`roles <math>`.
:mod:`sphinx.ext.imgmath` -- Render math as images
--------------------------------------------------
@ -128,10 +129,12 @@ built:
This extension puts math as-is into the HTML files. The JavaScript package
MathJax_ is then loaded and transforms the LaTeX markup to readable math live in
the browser.
the browser. Reminder: you should use the math :rst:dir:`directives <math>` and
:rst:role:`roles <math>`, not the native MathJax ``$$``, ``\(``, etc.
Because MathJax (and the necessary fonts) is very large, it is not included in
Sphinx.
Sphinx and your build will include resources from a external site (by
default cdnjs.cloudflare.com).
.. confval:: mathjax_path