Merge remote-tracking branch 'origin/public/docs/mathjax_ext' into pu…

…blic/doctests/furo

src/doc/common/themes/sage-classic/theme.conf

@@ -40,5 +40,3 @@ linkcolor        = #45529B
 # Background color for code blocks: very pale yellow
 codebgcolor      = #FFFFE5
 
-# MathJax settings filled in by conf.py
-mathjax_macros =

src/sage/docs/conf.py

@@ -2,7 +2,8 @@
 import sys
 import os
 import sphinx
-from sage.env import SAGE_DOC_SRC, SAGE_DOC, SAGE_SRC, THEBE_DIR, PPLPY_DOCS, MATHJAX_DIR
+from sage.env import SAGE_DOC_SRC, SAGE_DOC, THEBE_DIR, PPLPY_DOCS, MATHJAX_DIR
+from sage.misc.latex_macros import sage_mathjax_macros
 import sage.version
 from sage.misc.sagedoc import extlinks
 import dateutil.parser
@@ -13,6 +14,7 @@
 import sphinx.ext.intersphinx as intersphinx
 from IPython.lib.lexers import IPythonConsoleLexer, IPyLexer
 
+
 # General configuration
 # ---------------------
 
@@ -24,6 +26,9 @@
     "sage_docbuild.ext.sage_autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.extlinks",
+    # Mathjax integration
+    # https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax
+    "sphinx.ext.mathjax",
     "IPython.sphinxext.ipython_directive",
     "matplotlib.sphinxext.plot_directive",
 ]
@@ -267,13 +272,26 @@ def set_intersphinx_mappings(app, config):
 html_common_static_path = [os.path.join(SAGE_DOC_SRC, 'common', 'static'),
                            THEBE_DIR, 'static']
 
-# We use MathJax to build the documentation.
-extensions.append('sphinx.ext.mathjax')
-mathjax_path = 'MathJax.js?config=TeX-AMS_HTML-full,../mathjax_sage.js'
-
-from sage.misc.latex_macros import sage_mathjax_macros
-
-#html_theme_options["mathjax_macros"] = sage_mathjax_macros()
+# Configure MathJax
+# https://docs.mathjax.org/en/latest/options/input/tex.html
+mathjax3_config = {
+    "tex": {
+        # Add custom sage macros
+        # http://docs.mathjax.org/en/latest/input/tex/macros.html
+        "macros": sage_mathjax_macros(),
+        # Add $...$ as possible inline math
+        # https://docs.mathjax.org/en/latest/input/tex/delimiters.html#tex-and-latex-math-delimiters
+        "inlineMath": [["$", "$"], ["\\(", "\\)"]],
+        # Increase the limit the size of the string to be processed
+        # https://docs.mathjax.org/en/latest/options/input/tex.html#option-descriptions
+        "maxBuffer": 50 * 1024,
+        # Use colorv2 extension instead of built-in color extension
+        # https://docs.mathjax.org/en/latest/input/tex/extensions/autoload.html#tex-autoload-options
+        # https://docs.mathjax.org/en/latest/input/tex/extensions/colorv2.html#tex-colorv2
+        "autoload": {"color": [], "colorv2": ["color"]},
+    },
+}
+mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"
 
 mathjax_relative = os.path.basename(MATHJAX_DIR)
 

src/sage/misc/latex_macros.py

@@ -43,6 +43,7 @@
 contain '\newcommand' lines for each of the entries in ``macros``.
 """
 
+
 def produce_latex_macro(name, *sample_args):
     r"""
     Produce a string defining a LaTeX macro.
@@ -111,34 +112,35 @@ def convert_latex_macro_to_mathjax(macro):
     -  ``macro`` - LaTeX macro definition
 
     See the web page
-    http://www.mathjax.org/docs/1.1/options/TeX.html for a
+    https://docs.mathjax.org/en/latest/input/tex/macros.html for a
     description of the format for MathJax macros.
 
     EXAMPLES::
 
         sage: from sage.misc.latex_macros import convert_latex_macro_to_mathjax
         sage: convert_latex_macro_to_mathjax('\\newcommand{\\ZZ}{\\Bold{Z}}')
-        'ZZ: "\\\\Bold{Z}"'
+        ('ZZ', '\\Bold{Z}')
         sage: convert_latex_macro_to_mathjax('\\newcommand{\\GF}[1]{\\Bold{F}_{#1}}')
-        'GF: ["\\\\Bold{F}_{#1}",1]'
+        ('GF', ['\\Bold{F}_{#1}', 1])
     """
-    left_bracket = macro.find('[')
-    right_bracket = macro.find('[')
+    left_bracket = macro.find("[")
+    right_bracket = macro.find("[")
     if left_bracket >= 0:
-        right_bracket = macro.find(']')
-        num_args = macro[left_bracket+1:right_bracket]
+        right_bracket = macro.find("]")
+        num_args = int(macro[left_bracket + 1 : right_bracket])
     else:
         num_args = 0
-    start_name = macro.find('{') + 1  # add one to go past the backslash
-    end_name = macro.find('}')
-    name = macro[start_name+1:end_name]
-    start_defn = macro.find('{', end_name)
-    end_defn = macro.rfind('}')
-    defn = macro[start_defn+1: end_defn].replace('\\', '\\\\')
+    start_name = macro.find("{") + 1  # add one to go past the backslash
+    end_name = macro.find("}")
+    name = macro[start_name + 1 : end_name]
+    start_defn = macro.find("{", end_name)
+    end_defn = macro.rfind("}")
+    defn = macro[start_defn + 1 : end_defn]
     if num_args == 0:
-        return name + ': "' + defn + '"'
+        return name, defn
     else:
-        return name + ': ["' + defn + '",' + str(num_args) + ']'
+        return name, [defn, num_args]
+
 
 # To add a new macro for use in the Sage documentation, add a list or
 # tuple to the following list.  Each list (or tuple) should have the
@@ -176,6 +178,7 @@ def convert_latex_macro_to_mathjax(macro):
 # mathbf vs mathbb.  See latex.py for more information.
 sage_configurable_latex_macros = [r"\newcommand{\Bold}[1]{\mathbf{#1}}"]
 
+
 def sage_latex_macros():
     r"""
     Return list of LaTeX macros for Sage. This just runs the function
@@ -193,15 +196,17 @@ def sage_latex_macros():
 
 def sage_mathjax_macros():
     r"""
-    Return list of MathJax macro definitions for Sage as
-    JavaScript. This feeds each item output by
-    :func:`sage_latex_macros` to
+    Return Sage's macro definitions for usage with MathJax.
+    
+    This feeds each item output by :func:`sage_latex_macros` to
     :func:`convert_latex_macro_to_mathjax`.
 
     EXAMPLES::
 
         sage: from sage.misc.latex_macros import sage_mathjax_macros
         sage: sage_mathjax_macros()
-        ['ZZ: "\\\\Bold{Z}"', 'NN: "\\\\Bold{N}"', ...
+        {'Bold': ['\\mathbf{#1}', 1], 'CC': '\\Bold{C}', ...
     """
-    return [convert_latex_macro_to_mathjax(m) for m in sage_latex_macros()]
+    return dict(
+        [convert_latex_macro_to_mathjax(m) for m in sage_latex_macros()]
+    )

src/sage/misc/sagedoc.py

@@ -1486,7 +1486,6 @@ def __call__(self, obj, output='html', view=True):
     </script>
     <script type="text/javascript" src="%(static_path)s/jquery.js"></script>
     <script type="text/javascript" src="%(static_path)s/doctools.js"></script>
-    <script type="text/javascript" src="%(static_path)s/mathjax_sage.js"></script>
     <link rel="shortcut icon" href="%(static_path)s/favicon.ico" />
     <link rel="icon" href="%(static_path)s/sageicon.png" type="image/x-icon" />
   </head>