Math not rendered in downloaded documentation when offline #20951

cwfoo · 2021-09-06T08:05:56Z

Describe the issue linked to the documentation

I downloaded the zipped HTML documentation for Scikit-learn 0.24.2 from https://scikit-learn.org/dev/versions.html. However, the math in the documentation is not rendered when I am not connected to the internet. This is what I see when I view section 1.1 of the User Guide when offline:

The problem is caused by the following line, which will fail to load the MathJax script when offline.

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>

Suggest a potential alternative/fix

The solution is to bundle the MathJax script in the zipped HTML docs.

rth · 2021-09-06T08:26:06Z

Thanks! Feel free to open a PR to bundle that js file.

cwfoo · 2021-09-06T16:48:43Z

The other possible solution is to add export NO_MATHJAX=1 to build_tools/circle/build_doc.sh to render math as SVG images.

cwfoo · 2021-09-15T00:15:04Z

@rth I'm not familiar with the existing code. Perhaps this could work:

diff --git a/build_tools/circle/build_doc.sh b/build_tools/circle/build_doc.sh
index 8facdc5..8f11569 100755
--- a/build_tools/circle/build_doc.sh
+++ b/build_tools/circle/build_doc.sh
@@ -136,7 +136,7 @@ make_args="SPHINXOPTS=-T $make_args"  # show full traceback on exception
 # notation in the HTML documentation and to optimize the image files
 sudo -E apt-get -yq update --allow-releaseinfo-change
 sudo -E apt-get -yq --no-install-suggests --no-install-recommends \
-    install dvipng gsfonts ccache zip optipng
+    install dvipng dvisvgm gsfonts ccache zip optipng
 
 # deactivate circleci virtualenv and setup a miniconda env instead
 if [[ `type -t deactivate` ]]; then
@@ -195,6 +195,9 @@ then
     python build_tools/circle/list_versions.py > doc/versions.rst
 fi
 
+# Render math in HTML documentation for offline use
+export NO_MATHJAX=1
+
 # The pipefail is requested to propagate exit code
 set -o pipefail && cd doc && make $make_args 2>&1 | tee ~/log.txt

Issues:

Would this change affect the online docs at https://scikit-learn.org? From my understanding, we want to continue using MathJax for the online docs.
Can dvipng be removed?

thomasjpfan · 2021-09-15T02:06:42Z

Can dvipng be removed?

I think so. Most likely a old requirement from when we built the PDF.

I would prefer to use svg instead of loading mathjax just to reduce the amount of javascript that needs to be loaded. Although, the downside is that it adds another requirement for building the docs. I think one needs to install latex to install dvisvgm. Secondly, I recall setting NO_MATHJAX=1 increases the build time of the docs, but I have not checked in a while.

We can have the hosted version build with svg and recommend contributors build locally with mathjax enabled, but that leads to a different local build.

As a temporary fix, I think we should stick with bundling the mathjax for now. I see three options:

Vendor Mathjax's tex-chtml.js and configure sphinx to use it.
When we build the docs, download Mathjax's tex-chtml.js and configure sphinx to use it.
Use mathjax CDN on the hosted version. When packaging the zip, download Mathjax's tex-chtml.js , and use sed to rewrite every HTML file to link to the packaged text-chtml.js.

rth · 2021-09-15T06:43:49Z

Mathjax also appears to load a bunch of of fonts, which we might need to include if we bundle Mathjax.

note that all of these should be cached by the browser so they would only be loaded once. And once they are cached, it would likely mean less things to download than with SVG (where one would need to make one HTTP call per svg image I imagine)

cserpell · 2023-01-25T09:28:04Z

I have the same issue, local documentation does not show latex properly. Is there any way I could help to move this forward?

cwfoo added the Documentation label Sep 6, 2021

cwfoo mentioned this issue Sep 6, 2021

Add PDF download of documentation #20859

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Math not rendered in downloaded documentation when offline #20951

Math not rendered in downloaded documentation when offline #20951

Math not rendered in downloaded documentation when offline #20951

Math not rendered in downloaded documentation when offline #20951

Comments

Describe the issue linked to the documentation

Suggest a potential alternative/fix