From 8b28eeace8e453b58562f05889d83b464e8aa420 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sat, 9 Apr 2022 08:51:27 +0900 Subject: [PATCH 1/6] Upgrade to MathJax3 --- build/pkgs/mathjax/SPKG.rst | 7 +- build/pkgs/mathjax/checksums.ini | 6 +- build/pkgs/mathjax/package-version.txt | 2 +- build/pkgs/mathjax/spkg-src | 86 ++++++++++--------- .../sage-classic/static/mathjax_sage.js_t | 23 ----- src/doc/common/themes/sage-classic/theme.conf | 2 - src/sage/docs/conf.py | 64 +++++++++----- src/sage/misc/latex_macros.py | 36 ++++---- src/sage/misc/sagedoc.py | 1 - src/sage_docbuild/__init__.py | 1 - src/sage_docbuild/__main__.py | 5 ++ 11 files changed, 121 insertions(+), 112 deletions(-) delete mode 100644 src/doc/common/themes/sage-classic/static/mathjax_sage.js_t diff --git a/build/pkgs/mathjax/SPKG.rst b/build/pkgs/mathjax/SPKG.rst index e7c0a7edb27..9ffa178b269 100644 --- a/build/pkgs/mathjax/SPKG.rst +++ b/build/pkgs/mathjax/SPKG.rst @@ -6,7 +6,7 @@ Description MathJax is a JavaScript library for displaying mathematical formulas. -MathJax is used by the Jupyter notebook and the Sphinx documentation. +MathJax is used in the Sage documentation built by Sphinx. License ------- @@ -30,9 +30,8 @@ Special Update/Build Instructions None. + Patches ------- -- nopng_config.patch: prevent font warning messages since png files are - removed. See section "Trimming II -- not strictly necessary" of - https://github.com/mathjax/MathJax-docs/wiki/Guide%3A-reducing-size-of-a-mathjax-installation +None. diff --git a/build/pkgs/mathjax/checksums.ini b/build/pkgs/mathjax/checksums.ini index 4a2ee5ab7da..6a6b233b2ae 100644 --- a/build/pkgs/mathjax/checksums.ini +++ b/build/pkgs/mathjax/checksums.ini @@ -1,4 +1,4 @@ tarball=mathjax-VERSION.tar.gz -sha1=a1b31066a541167c65d6b43f24f3a06f03760662 -md5=02d1067dc06d9ca7d380457a49404766 -cksum=1204309472 +sha1=3f7abecf8cacd7f5d7f9ae6c3baca7739101c17d +md5=ba1a65ab58aaad6c84f39735c619bc34 +cksum=1142131398 diff --git a/build/pkgs/mathjax/package-version.txt b/build/pkgs/mathjax/package-version.txt index 65f95911c0b..944880fa15e 100644 --- a/build/pkgs/mathjax/package-version.txt +++ b/build/pkgs/mathjax/package-version.txt @@ -1 +1 @@ -2.7.4.p0 +3.2.0 diff --git a/build/pkgs/mathjax/spkg-src b/build/pkgs/mathjax/spkg-src index f77a8d88360..b1bfa4cdefe 100755 --- a/build/pkgs/mathjax/spkg-src +++ b/build/pkgs/mathjax/spkg-src @@ -4,13 +4,12 @@ set -e [ -n "${SAGE_ROOT}" ] || SAGE_ROOT="$(pwd)/../../../" - -# determine latest version. -GIT_VERSION="$(curl http://docs.mathjax.org/en/latest/installation.html | grep 'Current Version' | sed 's|^.*archive/||g' | sed 's/.zip".*//g')" +# determine the latest version +GIT_VERSION="$(curl https://github.com/mathjax/MathJax/releases | grep 'MathJax v' | head -1 | sed 's|^.*MathJax v||g' | sed 's/\s*$//g')" echo "GIT_VERSION=$GIT_VERSION" -# fetch and rename latest version. -URL="https://github.com/mathjax/MathJax/archive/${GIT_VERSION}.zip" +# fetch and rename the latest version +URL="https://github.com/mathjax/MathJax/archive/refs/tags/${GIT_VERSION}.zip" echo "Downloading $URL" rm -rf src if [ -z "$UPSTREAM_SOURCE_TARBALL" ]; then @@ -18,43 +17,52 @@ if [ -z "$UPSTREAM_SOURCE_TARBALL" ]; then else tar xzf "$UPSTREAM_SOURCE_TARBALL" fi -mv MathJax-${GIT_VERSION} src - -# Strip mathjax according to -# https://github.com/mathjax/MathJax-docs/wiki/Guide%3A-reducing-size-of-a-mathjax-installation - -# Trimming I -- removing files unnecessary for deployment -FILEDIRS_TO_REMOVE='docs/ test/ unpacked/ .gitignore README-branch.txt README.md bower.json' -for filedir in ${FILEDIRS_TO_REMOVE} ; do - rm -rf "src/${filedir}" -done - -# Trimming II -- not strictly necessary (requires the patch nopng_config.patch) -rm -rf 'src/fonts/HTML-CSS/TeX/png/' - -# Trimming III -- fonts -FONTS_TO_REMOVE='Asana-Math Gyre-Pagella Gyre-Termes Latin-Modern Neo-Euler' -for font in ${FONTS_TO_REMOVE} ; do - find . -type d -name "${font}" -prune -exec rm -rf {} \; -done - -FONT_FORMATS_TO_REMOVE='eot otf svg' -for fontformat in ${FONT_FORMATS_TO_REMOVE} ; do - find . -type d -name "${fontformat}" -prune -exec rm -rf {} \; -done - -# Trimming IV -- reducing input and output options -OUTPUT_OPTIONS_TO_REMOVE='NativeMML SVG' -for output in ${OUTPUT_OPTIONS_TO_REMOVE} ; do - rm -rf "src/jax/output/${output}" -done - -# repack -tar czf "$SAGE_ROOT/upstream/mathjax-${GIT_VERSION}.tar.gz" src + +# put files under mathjax directory +mkdir src +mv MathJax-${GIT_VERSION}/es5 src/mathjax +rm -r MathJax-${GIT_VERSION} + + +# The following block of commented-out lines were used to reduce the package +# size of MathJax2. We keep these lines for the future when we will want to +# reuse and rewrite them to remove unnecessary font files from MathJax3. + +## Trimming I -- removing files unnecessary for deployment +#FILEDIRS_TO_REMOVE='docs/ test/ unpacked/ .gitignore README-branch.txt README.md bower.json' +#for filedir in ${FILEDIRS_TO_REMOVE} ; do +# rm -rf "src/${filedir}" +#done +# +## Trimming II -- not strictly necessary (requires the patch nopng_config.patch) +#rm -rf 'src/fonts/HTML-CSS/TeX/png/' +# +## Trimming III -- fonts +#FONTS_TO_REMOVE='Asana-Math Gyre-Pagella Gyre-Termes Latin-Modern Neo-Euler' +#for font in ${FONTS_TO_REMOVE} ; do +# find . -type d -name "${font}" -prune -exec rm -rf {} \; +#done +# +#FONT_FORMATS_TO_REMOVE='eot otf svg' +#for fontformat in ${FONT_FORMATS_TO_REMOVE} ; do +# find . -type d -name "${fontformat}" -prune -exec rm -rf {} \; +#done +# +## Trimming IV -- reducing input and output options +#OUTPUT_OPTIONS_TO_REMOVE='NativeMML SVG' +#for output in ${OUTPUT_OPTIONS_TO_REMOVE} ; do +# rm -rf "src/jax/output/${output}" +#done + + +PACKAGE_VERSION=${GIT_VERSION} + +# repackage +tar czf "$SAGE_ROOT/upstream/mathjax-${PACKAGE_VERSION}.tar.gz" src rm -rf src # update package info -echo "${GIT_VERSION}" > 'package-version.txt' +echo "${PACKAGE_VERSION}" > 'package-version.txt' "$SAGE_ROOT"/sage --package fix-checksum mathjax diff --git a/src/doc/common/themes/sage-classic/static/mathjax_sage.js_t b/src/doc/common/themes/sage-classic/static/mathjax_sage.js_t deleted file mode 100644 index b261f2265a3..00000000000 --- a/src/doc/common/themes/sage-classic/static/mathjax_sage.js_t +++ /dev/null @@ -1,23 +0,0 @@ -MathJax.Hub.Config({ - imageFont: null, - tex2jax: { - inlineMath: [['$','$'],['\\(','\\)']], - processEscapes: true, - }, - styles: { - ".MathJax .mo, .MathJax .mi": { - color: "inherit ! important" - } - }, - TeX: { - MAXBUFFER: 50*1024, - - Macros: { - {{ theme_mathjax_macros|join(',\n') }} - } - } -}); - -// This path is a little funny because we have to load our local -// config file as '../mathjax_sage' in the theme conf.py -MathJax.Ajax.loadComplete("[MathJax]/config/../mathjax_sage.js") diff --git a/src/doc/common/themes/sage-classic/theme.conf b/src/doc/common/themes/sage-classic/theme.conf index cc6279a2633..fbde86a94ac 100644 --- a/src/doc/common/themes/sage-classic/theme.conf +++ b/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 = diff --git a/src/sage/docs/conf.py b/src/sage/docs/conf.py index be9c4fb278d..58db12dff41 100644 --- a/src/sage/docs/conf.py +++ b/src/sage/docs/conf.py @@ -4,7 +4,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 @@ -15,19 +16,23 @@ import sphinx.ext.intersphinx as intersphinx from IPython.lib.lexers import IPythonConsoleLexer, IPyLexer + # General configuration # --------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sage_docbuild.ext.inventory_builder', - 'sage_docbuild.ext.multidocs', - 'sage_docbuild.ext.sage_autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.extlinks', - 'IPython.sphinxext.ipython_directive', - 'matplotlib.sphinxext.plot_directive', - 'jupyter_sphinx'] +extensions = [ + 'sage_docbuild.ext.inventory_builder', + 'sage_docbuild.ext.multidocs', + 'sage_docbuild.ext.sage_autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.extlinks', + 'sphinx.ext.mathjax', + 'IPython.sphinxext.ipython_directive', + 'matplotlib.sphinxext.plot_directive', + 'jupyter_sphinx', +] jupyter_execute_default_kernel = 'sagemath' @@ -263,21 +268,36 @@ 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_relative = os.path.basename(MATHJAX_DIR) +if os.environ.get('SAGE_USE_CDNS', 'no') == 'yes': + mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js" +else: + mathjax_path = 'mathjax/tex-chtml.js' + html_common_static_path += [MATHJAX_DIR] -# It would be really nice if sphinx would copy the entire mathjax -# directory, (so we could have a _static/mathjax directory), rather than -# the contents of the directory -html_common_static_path.append(MATHJAX_DIR) -exclude_patterns += ['**/' + os.path.join(mathjax_relative, i) - for i in ('docs', 'README*', 'test', 'unpacked', 'LICENSE')] +# A list of glob-style patterns that should be excluded when looking for source +# files. They are matched against the source file names relative to the +# source directory, using slashes as directory separators on all platforms. +exclude_patterns = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/src/sage/misc/latex_macros.py b/src/sage/misc/latex_macros.py index eaaf77a0f18..1605d8a22f5 100644 --- a/src/sage/misc/latex_macros.py +++ b/src/sage/misc/latex_macros.py @@ -43,14 +43,16 @@ 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. INPUT: - - ``name`` - name of macro to be defined, also name of corresponding Sage object - - ``sample_args`` - (optional) sample arguments for this Sage object + - ``name`` -- name of macro to be defined, also name of corresponding Sage object + + - ``sample_args`` -- (optional) sample arguments for this Sage object EXAMPLES:: @@ -108,37 +110,38 @@ def convert_latex_macro_to_mathjax(macro): INPUT: - - ``macro`` - LaTeX macro definition + - ``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('[') if left_bracket >= 0: right_bracket = macro.find(']') - num_args = macro[left_bracket+1:right_bracket] + 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] + 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('\\', '\\\\') + 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 +179,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 +197,15 @@ 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()) diff --git a/src/sage/misc/sagedoc.py b/src/sage/misc/sagedoc.py index 6e326a1c329..37fd5d8b6e6 100644 --- a/src/sage/misc/sagedoc.py +++ b/src/sage/misc/sagedoc.py @@ -1486,7 +1486,6 @@ def __call__(self, obj, output='html', view=True): - diff --git a/src/sage_docbuild/__init__.py b/src/sage_docbuild/__init__.py index 8b137891791..e69de29bb2d 100644 --- a/src/sage_docbuild/__init__.py +++ b/src/sage_docbuild/__init__.py @@ -1 +0,0 @@ - diff --git a/src/sage_docbuild/__main__.py b/src/sage_docbuild/__main__.py index a46a858b11a..8c6e9031b82 100644 --- a/src/sage_docbuild/__main__.py +++ b/src/sage_docbuild/__main__.py @@ -303,6 +303,9 @@ def setup_parser(): standard.add_argument("--no-prune-empty-dirs", dest="no_prune_empty_dirs", action="store_true", help="do not prune empty directories in the documentation sources") + standard.add_argument("--use-cdns", dest="use_cdns", default=False, + action="store_true", + help="assume internet connection and use CDNs; in particular, use MathJax CDN") standard.add_argument("-N", "--no-colors", dest="color", action="store_false", help="do not color output; does not affect children") @@ -471,6 +474,8 @@ def excepthook(*exc_info): os.environ['SAGE_SKIP_PLOT_DIRECTIVE'] = 'yes' if args.skip_tests: os.environ['SAGE_SKIP_TESTS_BLOCKS'] = 'True' + if args.use_cdns: + os.environ['SAGE_USE_CDNS'] = 'yes' ABORT_ON_ERROR = not args.keep_going From c34be8ebf5653143da5efaab98049babe3641fe3 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sat, 9 Apr 2022 11:43:07 +0900 Subject: [PATCH 2/6] Fix mathjax3 bug in website/templates/index.html --- src/doc/en/website/templates/index.html | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/doc/en/website/templates/index.html b/src/doc/en/website/templates/index.html index 5f34a99dc62..d8895243052 100644 --- a/src/doc/en/website/templates/index.html +++ b/src/doc/en/website/templates/index.html @@ -15,6 +15,13 @@ display: none; {%- endif %} } + table.contentstable { + align: center; + border-spacing: 20px; + } + table.contentstable span { {# trac #33600 comment:22 #} + border-spacing: initial; + } {% endblock %} @@ -33,7 +40,7 @@

Tutorials and FAQ

- +

From e0a5d39e7bdf9fe796580c54b00b3cb89133ea7d Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sat, 9 Apr 2022 21:07:27 +0900 Subject: [PATCH 3/6] Remove commented-out lines --- build/pkgs/mathjax/spkg-src | 34 ---------------------------------- 1 file changed, 34 deletions(-) diff --git a/build/pkgs/mathjax/spkg-src b/build/pkgs/mathjax/spkg-src index b1bfa4cdefe..bd7fa941cc9 100755 --- a/build/pkgs/mathjax/spkg-src +++ b/build/pkgs/mathjax/spkg-src @@ -23,38 +23,6 @@ mkdir src mv MathJax-${GIT_VERSION}/es5 src/mathjax rm -r MathJax-${GIT_VERSION} - -# The following block of commented-out lines were used to reduce the package -# size of MathJax2. We keep these lines for the future when we will want to -# reuse and rewrite them to remove unnecessary font files from MathJax3. - -## Trimming I -- removing files unnecessary for deployment -#FILEDIRS_TO_REMOVE='docs/ test/ unpacked/ .gitignore README-branch.txt README.md bower.json' -#for filedir in ${FILEDIRS_TO_REMOVE} ; do -# rm -rf "src/${filedir}" -#done -# -## Trimming II -- not strictly necessary (requires the patch nopng_config.patch) -#rm -rf 'src/fonts/HTML-CSS/TeX/png/' -# -## Trimming III -- fonts -#FONTS_TO_REMOVE='Asana-Math Gyre-Pagella Gyre-Termes Latin-Modern Neo-Euler' -#for font in ${FONTS_TO_REMOVE} ; do -# find . -type d -name "${font}" -prune -exec rm -rf {} \; -#done -# -#FONT_FORMATS_TO_REMOVE='eot otf svg' -#for fontformat in ${FONT_FORMATS_TO_REMOVE} ; do -# find . -type d -name "${fontformat}" -prune -exec rm -rf {} \; -#done -# -## Trimming IV -- reducing input and output options -#OUTPUT_OPTIONS_TO_REMOVE='NativeMML SVG' -#for output in ${OUTPUT_OPTIONS_TO_REMOVE} ; do -# rm -rf "src/jax/output/${output}" -#done - - PACKAGE_VERSION=${GIT_VERSION} # repackage @@ -64,5 +32,3 @@ rm -rf src # update package info echo "${PACKAGE_VERSION}" > 'package-version.txt' "$SAGE_ROOT"/sage --package fix-checksum mathjax - - From 1cd2b499a7155cf6037965abbdad594200efa634 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 10 Apr 2022 10:39:08 +0900 Subject: [PATCH 4/6] Add upstream_url --- build/pkgs/mathjax/checksums.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/build/pkgs/mathjax/checksums.ini b/build/pkgs/mathjax/checksums.ini index 6a6b233b2ae..76e362f6b28 100644 --- a/build/pkgs/mathjax/checksums.ini +++ b/build/pkgs/mathjax/checksums.ini @@ -2,3 +2,4 @@ tarball=mathjax-VERSION.tar.gz sha1=3f7abecf8cacd7f5d7f9ae6c3baca7739101c17d md5=ba1a65ab58aaad6c84f39735c619bc34 cksum=1142131398 +upstream_url=https://trac.sagemath.org/raw-attachment/ticket/25833/mathjax-3.2.0.tar.gz From a72a8e387ef56db5bc181a9b3c73172ba63f00e1 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Thu, 14 Apr 2022 16:41:53 +0900 Subject: [PATCH 5/6] Fix to make the reference main page less flickering --- src/doc/en/reference/footer.txt | 8 ++++---- src/doc/en/reference/index.rst | 9 ++++++++- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/src/doc/en/reference/footer.txt b/src/doc/en/reference/footer.txt index 94b024d6dab..22b60ffa26f 100644 --- a/src/doc/en/reference/footer.txt +++ b/src/doc/en/reference/footer.txt @@ -1,13 +1,13 @@ Indices and Tables ================== +* `Index <../genindex.html>`_ +* `Module Index <../py-modindex.html>`_ +* `Search Page <../search.html>`_ + .. comment: the following math environment forces Sphinx to load MathJax in the index.rst pages. Do not delete it! .. math:: :nowrap: - -* `Index <../genindex.html>`_ -* `Module Index <../py-modindex.html>`_ -* `Search Page <../search.html>`_ diff --git a/src/doc/en/reference/index.rst b/src/doc/en/reference/index.rst index d7667e195ea..065bccac955 100644 --- a/src/doc/en/reference/index.rst +++ b/src/doc/en/reference/index.rst @@ -7,7 +7,7 @@ Welcome to the Sage Reference Manual! Here you find documentation for all of `Sage `_'s features, illustrated with lots of examples. A thematic index follows. -This documentation is licensed under the `Creative Commons Attribution-Share Alike 3.0 License`__:math:`.` +This documentation is licensed under the `Creative Commons Attribution-Share Alike 3.0 License`__. __ http://creativecommons.org/licenses/by-sa/3.0/ @@ -175,3 +175,10 @@ Indices and Tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + +.. + comment: the following math environment forces Sphinx to load MathJax + in the index.rst pages. Do not delete it! + +.. math:: + :nowrap: From 2535a91fbc2e94a683f2e840a281bf917d5ff470 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Fri, 29 Apr 2022 12:35:37 +0900 Subject: [PATCH 6/6] Restore changes to conf.py --- src/sage_docbuild/conf.py | 68 ++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 26 deletions(-) diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index e34c1d88aca..13c969a0ec8 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -1,11 +1,8 @@ -r""" -Sphinx configurations -""" - 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 @@ -16,19 +13,23 @@ import sphinx.ext.intersphinx as intersphinx from IPython.lib.lexers import IPythonConsoleLexer, IPyLexer + # General configuration # --------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sage_docbuild.ext.inventory_builder', - 'sage_docbuild.ext.multidocs', - 'sage_docbuild.ext.sage_autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.extlinks', - 'IPython.sphinxext.ipython_directive', - 'matplotlib.sphinxext.plot_directive', - 'jupyter_sphinx'] +extensions = [ + 'sage_docbuild.ext.inventory_builder', + 'sage_docbuild.ext.multidocs', + 'sage_docbuild.ext.sage_autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.extlinks', + 'sphinx.ext.mathjax', + 'IPython.sphinxext.ipython_directive', + 'matplotlib.sphinxext.plot_directive', + 'jupyter_sphinx', +] jupyter_execute_default_kernel = 'sagemath' @@ -264,21 +265,36 @@ 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_relative = os.path.basename(MATHJAX_DIR) +if os.environ.get('SAGE_USE_CDNS', 'no') == 'yes': + mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js" +else: + mathjax_path = 'mathjax/tex-chtml.js' + html_common_static_path += [MATHJAX_DIR] -# It would be really nice if sphinx would copy the entire mathjax -# directory, (so we could have a _static/mathjax directory), rather than -# the contents of the directory -html_common_static_path.append(MATHJAX_DIR) -exclude_patterns += ['**/' + os.path.join(mathjax_relative, i) - for i in ('docs', 'README*', 'test', 'unpacked', 'LICENSE')] +# A list of glob-style patterns that should be excluded when looking for source +# files. They are matched against the source file names relative to the +# source directory, using slashes as directory separators on all platforms. +exclude_patterns = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format.