New math documentation (salvaged from #1669)

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Jun 6, 2015 · 5d2dc48 · 5d2dc48
1 parent 3469045
commit 5d2dc48
Show file tree

Hide file tree

Showing 3 changed files with 56 additions and 22 deletions.
diff --git a/docs/manual.txt b/docs/manual.txt
@@ -1,7 +1,6 @@
 .. title: The Nikola Handbook
 .. slug: handbook
 .. date: 2012-03-30 23:00:00 UTC-03:00
-.. tags: mathjax
 .. link:
 .. description:
 
@@ -1413,42 +1412,77 @@ different ones, or about other web servers, please share!
 #. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not
    downloaded from your server.
 
-reStructuredText Extensions
----------------------------
+Math
+----
+
+Nikola supports math input via MathJax.  It is activated via the math roles and
+directives of reStructuredText and the usual LaTeX delimiters (``\(inline\)``
+and ``\[display\]``) for other input formats.
+
+We **DO NOT** support the old, deprecated and error-prone ``$inline$``
+delimiters by default. If you want to use them, please add them manually,
+like this:
+
+.. code:: python
+
+   """
+    MATHJAX_CONFIG = """
+    <script type="text/x-mathjax-config">
+    MathJax.Hub.Config({
+        tex2jax: {
+            inlineMath: [ ['$','$'], ["\\\(","\\\)"] ],
+            displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ],
+            processEscapes: true
+        },
+        displayAlign: 'left', // Change this to 'center' to center equations.
+        "HTML-CSS": {
+            styles: {'.MathJax_Display': {"margin": 0}}
+        }
+    });
+    </script>
+    """
 
-Nikola includes support for a few directives and roles that are not part of docutils, but which
-we think are handy for website development.
+Inline mathematics are produced using the reST `math` **role** or the ``\(…\)`` delimiters:
 
-MathJax
-~~~~~~~
-
-Nikola supports math input via MathJax.  It uses the usual math roles and
-directives of reStructuredText.
+Euler’s formula: :math:`e^{ix} = \cos x + i\sin x`
 
-In order to use them in your posts, you **must** add the special ``mathjax`` tag.
+In reST:
 
-Inline mathematics (equivalent to single dollar signs or backslash-parentheses
-in LaTeX) are produced using the `math` **role**:
+.. code:: restructuredtext
 
-Euler’s formula: :math:`e^{ix} = \cos x + i\sin x`
+    Euler’s formula: :math:`e^{ix} = \cos x + i\sin x`
 
-::
+In other input formats::
 
-    Euler’s formula: :math:`e^{ix} = \cos x + i\sin x`
+    Euler’s formula: \(e^{ix} = \cos x + i\sin x\)
 
-Display mathematics (equivalent to double dollar signs or backslash-brackets in
-LaTeX) are produced using the `math` **directive**:
+Display mathematics are produced using the reST `math` **directive** or the ``\[…\]`` delimiters:
 
 .. math::
 
    \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C
 
+
+In reST:
+
 ::
 
    .. math::
 
       \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C
 
+In other input formats:
+
+::
+
+    \[\int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C\]
+
+reStructuredText Extensions
+---------------------------
+
+Nikola includes support for a few directives and roles that are not part of docutils, but which
+we think are handy for website development.
+
 Media
 ~~~~~
 

diff --git a/nikola/nikola.py b/nikola/nikola.py
@@ -642,15 +642,15 @@ def __init__(self, **config):
             utils.LOGGER.error("Punycode of {}: {}".format(_bnl, _bnl.encode('idna')))
             sys.exit(1)
 
-        # todo: remove in v8
+        # TODO: remove in v8
         if not isinstance(self.config['DEPLOY_COMMANDS'], dict):
             utils.LOGGER.warn("A single list as DEPLOY_COMMANDS is deprecated.  DEPLOY_COMMANDS should be a dict, with deploy preset names as keys and lists of commands as values.")
             utils.LOGGER.warn("The key `default` is used by `nikola deploy`:")
             self.config['DEPLOY_COMMANDS'] = {'default': self.config['DEPLOY_COMMANDS']}
             utils.LOGGER.warn("DEPLOY_COMMANDS = {0}".format(self.config['DEPLOY_COMMANDS']))
             utils.LOGGER.info("(The above can be used with `nikola deploy` or `nikola deploy default`.  Multiple presets are accepted.)")
 
-        # todo: remove and change default in v8
+        # TODO: remove and change default in v8
         if 'BLOG_TITLE' in config and 'WRITE_TAG_CLOUD' not in config:
             # BLOG_TITLE is a hack, otherwise the warning would be displayed
             # when conf.py does not exist

diff --git a/tests/test_rst_compiler.py b/tests/test_rst_compiler.py
@@ -122,8 +122,8 @@ def test_test(self):
 class MathTestCase(ReSTExtensionTestCase):
     sample = ':math:`e^{ix} = \cos x + i\sin x`'
 
-    def test_mathjax(self):
-        """ Test that math is outputting MathJax."""
+    def test_math(self):
+        """ Test that math is outputting TeX code."""
         self.basic_test()
         self.assertHTMLContains("span", attributes={"class": "math"},
                                 text="\(e^{ix} = \cos x + i\sin x\)")