Clarify MathJax extension usage: edits from review

This commit is contained in:
Richard Darst 2019-03-29 16:40:18 +02:00
parent dd0246c6dc
commit 277588f2f9

View File

@ -16,7 +16,7 @@ Math support for HTML outputs in Sphinx
Since mathematical notation isn't natively supported by HTML in any way, Sphinx
gives a math support to HTML document with several extensions. These use the
Sphinx :rst:dir:`directives <math>` and :rst:role:`roles <math>`.
reStructuredText math :rst:dir:`directive <math>` and :rst:role:`role <math>`.
:mod:`sphinx.ext.imgmath` -- Render math as images
--------------------------------------------------
@ -129,12 +129,16 @@ 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. Reminder: you should use the math :rst:dir:`directives <math>` and
:rst:role:`roles <math>`, not the native MathJax ``$$``, ``\(``, etc.
the browser.
Because MathJax (and the necessary fonts) is very large, it is not included in
Sphinx and your build will include resources from a external site (by
default cdnjs.cloudflare.com).
Sphinx but is set to automatically include it from a third-party site.
.. attention::
You should use the math :rst:dir:`directive <math>` and
:rst:role:`role <math>`, not the native MathJax ``$$``, ``\(``, etc.
.. confval:: mathjax_path
@ -143,8 +147,9 @@ default cdnjs.cloudflare.com).
The default is the ``https://`` URL that loads the JS files from the
`cdnjs`__ Content Delivery Network. See the `MathJax Getting Started
page`__ for details. If you want MathJax to be available offline, you have
to download it and set this value to a different path.
page`__ for details. If you want MathJax to be available offline or
without including resources from a third-party site, you have to
download it and set this value to a different path.
__ https://cdnjs.com