From 8c787f3bbaeae9fb06a2e75d57a2103badd83cf5 Mon Sep 17 00:00:00 2001
From: Frank Schultz <scf175@googlemail.com>
Date: Sat, 5 Jun 2021 18:16:01 +0200
Subject: [PATCH] build doc fix, use sphinx4, mathjax2, html_css_files

---
 doc/conf.py | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index caec59a..35b2874 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -35,7 +35,6 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',  # support for NumPy-style docstrings
     'sphinx.ext.intersphinx',
@@ -95,7 +94,22 @@
 }
 plot_formats = ['svg', 'pdf']
 
-mathjax_config = {
+# use mathjax2 with
+# https://github.com/spatialaudio/nbsphinx/issues/572#issuecomment-853389268
+# and 'TeX' dictionary
+# in future we might switch to mathjax3 once the
+# 'begingroup' extension is available
+# http://docs.mathjax.org/en/latest/input/tex/extensions/begingroup.html#begingroup
+# https://mathjax.github.io/MathJax-demos-web/convert-configuration/convert-configuration.html
+mathjax_path = ('https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js'
+                '?config=TeX-AMS-MML_HTMLorMML')
+mathjax2_config = {
+    'tex2jax': {
+        'inlineMath': [['$', '$'], ['\\(', '\\)']],
+        'processEscapes': True,
+        'ignoreClass': 'document',
+        'processClass': 'math|output_area',
+    },
     'TeX': {
         'extensions': ['newcommand.js', 'begingroup.js'],  # Support for \gdef
     },
@@ -219,9 +233,7 @@
 
 # -- Options for HTML output ----------------------------------------------
 
-def setup(app):
-    """Include custom theme files to sphinx HTML header"""
-    app.add_stylesheet('css/title.css')
+html_css_files = ['css/title.css']
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.