Build system: make the mathjax_path option of Sphinx configurable from meson

This replaces the old hack which was using a local Linux-specific symlink. Now,
the Dynare default is the same as in Sphinx, i.e. rely on a CDN for delivering
MathJax.

Adapt our CI accordingly to continue using MathJax from the Debian package
there (to avoid privacy issues related to the use of a CDN).

.gitlab-ci.yml

@@ -49,8 +49,12 @@ build_doc:
   stage: build
   script:
     - meson rewrite kwargs set project / version "$VERSION"
-    - meson setup -Dbuild_for=octave build-doc
+    # Use a local copy of MathJax to avoid using CDN (which are a privacy issue)
+    # NB: Debian 12 “Bookworm” has MathJax 2. The following needs to be updated
+    #     when Debian moves to MathJax 3.
+    - meson setup -Dbuild_for=octave -Dmathjax_path=mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML build-doc
     - meson compile -v -C build-doc doc
+    - cp -dR /usr/share/javascript/mathjax build-doc/dynare-manual.html/_static/
   artifacts:
     paths:
       - build-doc/
@@ -60,7 +64,6 @@ pkg_source:
   stage: pkg
   script:
     - meson rewrite kwargs set project / version "$VERSION"
-    - rm doc/manual/source/_static/mathjax && sed -i "/^mathjax_path *=/d" doc/manual/source/conf.py
     - git commit -a -m "Source for $VERSION"
     - meson setup -Dbuild_for=octave build-src
     - meson dist -C build-src --no-tests
@@ -204,8 +207,6 @@ deploy_manual_unstable:
   dependencies:
     - build_doc
   script:
-    - rm -rf build-doc/dynare-manual.html/_static/mathjax
-    - ln -s /usr/share/javascript/mathjax build-doc/dynare-manual.html/_static/mathjax
     - rsync --recursive --links --delete build-doc/dynare-manual.html/ /srv/www.dynare.org/manual-unstable/
 
 deploy_snapshot_unstable:

doc/manual/source/_static/mathjax

@@ -1 +0,0 @@
-/usr/share/javascript/mathjax/

doc/manual/source/conf.py

@@ -31,8 +31,6 @@ templates_path = ['_templates']
 
 html_static_path = ['_static']
 
-mathjax_path = 'mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
-
 master_doc = 'index'
 
 project = u'Dynare'

meson.build

@@ -552,6 +552,10 @@ sphinx_src = [ 'doc/manual/source/conf.py',
 sphinx_defines = [ '-D', 'release=' + meson.project_version(),
                    '-D', 'version=' + meson.project_version() ]
 
+if get_option('mathjax_path') != ''
+  sphinx_defines += [ '-D', 'mathjax_path=' + get_option('mathjax_path') ]
+endif
+
 dynare_manual_html = custom_target('dynare-manual.html',
                                    output : 'dynare-manual.html', input : sphinx_src,
                                    command : [ sphinx_build_exe, '-b', 'html', sphinx_defines,

meson_options.txt

@@ -1,3 +1,4 @@
 # TODO: Rename this file to meson.options when meson ⩾ 1.1 is required
 option('build_for', type : 'combo', choices : [ 'matlab', 'octave' ], description : 'Whether to build for MATLAB or Octave')
 option('matlab_path', type : 'string', description : 'Absolute directory containing the MATLAB installation')
+option('mathjax_path', type : 'string', description : 'Path to the MathJax JavaScript file to include in the HTML documentation produced by Sphinx; leave empty to use the default CDN')