Upgrade to Sphinx 4.0.0 (#1387)

Changes: https://www.sphinx-doc.org/en/master/changes.html#release-4-0-0-released-may-09-2021 Things to note: - docutils updated to 0.17 https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-17-2021-04-03 the big change here is to use semantic elements, <div class="section"> is now <section>, I see this a whole bunch when I diff the output HTML. - supposedly some html themes break due to the docutils change, probably due to divs not matching, I don't see any visible breakage, so it should be fine - mathjax 3 https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html it's faster to render, we need to tweak our configuration a bit, to camelCase, so updated it in conf.py I diffed the output html, some differences I noted: - div -> section as noted above - a new meta tag for Docutils - link tag for css, the type and href attributs swapped places - script tag for documetation_options, id and data-url_root swapped places - some css changes in sphinx css files Co-authored-by: Ms2ger <[email protected]>
WebAssembly · Oct 29, 2021 · b6307dc · b6307dc
1 parent 93054e7
commit b6307dc
Show file tree

Hide file tree

Showing 4 changed files with 8 additions and 7 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -52,7 +52,7 @@ jobs:
       - run: pip install bikeshed && bikeshed update
       - run: pip install six
       - run: sudo apt-get update -y && sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
-      - run: pip install sphinx==3.5.4
+      - run: pip install sphinx==4.0.0
       - run: cd document/core && make all
       - uses: actions/upload-artifact@v2
         with:

diff --git a/document/README.md b/document/README.md
@@ -42,7 +42,7 @@ pipenv shell
 Install Python dependencies:
 
 ```
-pipenv install Sphinx==3.5.4
+pipenv install Sphinx==4.0.0
 ```
 
 ### Checking out the repository

diff --git a/document/core/conf.py b/document/core/conf.py
@@ -492,8 +492,9 @@
 .. include:: /""" + pwd + """/util/macros.def
 """
 
-# https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax_config
-# http://docs.mathjax.org/en/v2.7-latest/options/input-processors/TeX.html
-mathjax_config = {
-    'TeX': { 'MAXBUFFER': 30*1024 },
+# https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax3_config
+# https://docs.mathjax.org/en/latest/web/configuration.html#configuration
+# https://docs.mathjax.org/en/latest/options/input/tex.html#tex-maxbuffer
+mathjax3_config = {
+    'tex': { 'maxBuffer': 30*1024 },
 }
diff --git a/document/core/util/bikeshed/conf.py b/document/core/util/bikeshed/conf.py
@@ -38,4 +38,4 @@
 assert(main_macros_def in rst_prolog)
 rst_prolog  = rst_prolog.replace(main_macros_def, "/" + pwd + "/util/macros.def")
 
-del mathjax_config
+del mathjax3_config