how to share location of local mathjax?

[berlin2123]

I have muti projects, which want to use the same local mathjax, as saying in www.sphinx-doc.org: 'If you host more than one Sphinx documentation set on one server, it is advisable to install MathJax in a shared location.'
However, could not using a path not inside _build/html

such as,

/data/project1/_build/html           # project1
/data/project2/_build/html           # project2
/data/mathjax/es5/tex-chtml.js       # mathjax path

then, not work: If set mathjax_path = '../../../../mathjax/es5/tex-chtml.js' , i.e. the relative path of /data/project1/_build/html/_static,
it will only make browser to load matjax file from http://IP:8000/mathjax/es5/tex-chtml.js, instead of from http://IP:8000/../../../mathjax/es5/tex-chtml.js.
However, file /data/project1/_build/html/mathjax/es5/tex-chtml.js does not exist. So not work.

what will only works is copy mathjax files into a path inside /data/project1/_build/html and change the mathjax_path too,
However, this way does not share mathjax bettween projects.

So, How to share?

[berlin2123]

I checked out for httpd of using files outside of DocumentRoot, it could be done by Alias inside httpd config file. However, what I am using is sphinx-autobuild, which is based on livereload and do not support Alias.

But livereload supports symbolic links, such as:

ln -s /data/mathjax /data/project1/_build/html/_static/mathjax
# and in conf.py:
mathjax_path = 'mathjax/es5/tex-chtml.js'

will work.

BUT, This solution requires us to create symbolic links manually, especially after run make clean.
So, does it possible to automatically create symbolic links in the conf.py file or somewhere else? just when find out the mathjax_path is outside of DocumentRoot.

[berlin2123]

Temporary solution for automatic copying of mathjax files:

mkdir /data/mathjax/_static
ln -s /data/mathjax/es5 /data/mathjax/_static/mathjax

# then, edit conf.py
html_static_path += ['../../mathjax/_static']    #  relative to configuration directory
mathjax_path = 'mathjax/tex-chtml-full.js'       #  relative to `_build/html/_static`

the files inside html_static_path[i] will be copied into _build/html/_static. so It works.

Though this isn't really shared storage for mathjax, at least all projects work automatically now.

[jdillard]

I started by using this method:

html_static_path = ['_static', '../common/_static']

mathjax_path = 'MathJax/MathJax.js' # files located in ../common/_static

But, when deployed all the MathJax assets were deployed separately for each project, which slowed deploy times (lots of files) and also ate up a lot more storage over time.

Since then, I have switched to having a single project deploy with the local MathJax files like it normally would, then all other projects use mathjax_url_schema to reference those deployed assets (giving a little more control vs a third party CDN). It might take some custom logic to arrive at the appropriate schema if you support multiple branches/etc, but I haven't really had any issues once switching and deploy times/storage were improved (the more projects the bigger the improvement)

[berlin2123]

you are ritht, using a self-hosted mathjax_url_schema could work and save storge.

[berlin2123]

I'd love to know: how did the author share mathjax when he originally wrote that install MathJax in a shared location sentence.

I checked that is added by (1675a45) into sphinx.
I find out that is writen by Kevin Dunn.
However, I don't know how to contact him.

[berlin2123]

I'd love to know: how did the author share mathjax when he originally wrote that install MathJax in a shared location sentence.

I checked that is added by (1675a45) into sphinx.
I find out that is writen by Kevin Dunn.
However, I don't know how to contact him.

[jayaddison]

Ah, my question was not clear. I meant, in an HTML page of the build dst: how many <script src="...mathjax stuff..."> elements appear in the source of the page?

[berlin2123]

in one page, it's:

<script defer="defer" src="_static/mathjax/tex-chtml-full.js?v=97d8d0d7"></script>

seems only one js file.

however, if I just copy or link only the tex-chtml-full.js file into OutDir at the same position, maths do not shows in webpages. If copy or link the mathjax/es5 dir into OutDir, all math works fine.

[jayaddison]

seems only one js file.

Ok, great.

<script defer="defer" src="_static/mathjax/tex-chtml-full.js?v=97d8d0d7"></script>

What version of MathJax is this? For v3.2.2 of it, I get CRC32 and SHA256:

• CRC32: 498d9c6c (like ?v=........)
• SHA256: 3257a831b5cba20e662dc9b840a5a88d2015aab4d50868fa251cb97f1e31a2fd

(it may not seem relevant - but I have an idea that instead of using capitalization, asking the configuration manager to include a checksum with each individual filename could be better. only valid for files, not directories -- but we only need one file, for MathJax)

[jayaddison]

(also note: I learned this after my last comment: there is already a mathjax_options['integrity'] setting)

[berlin2123]

I am not submitting that PR just for mathjax. it makes more sense to link images and video files.

[jdillard]

I don't know if I would read into it to much, as implementation is likely so individual that it would hard to give more detail. Given the context, I have feeling they meant a shared hosted location, whether that's in a stand alone location or as part of a Sphinx project.

[berlin2123]

maybe.

[berlin2123]

or back to the the soft-link solution.
if the link could run inside conf.py, all will be fine.
But I don't know the keywords to abtain the bulid html path inside conf.py.

[berlin2123]

The build path may not be a constant, such as running by sphinx-autobuild. However, I can't get The build path while run conf.py, ,so manually edit conf.py my not a good solution:

# edit conf.py
import os
os.system('ln -s -f path/to/mathjax  path/to/build/html/_static/mathjax')     # manually edit for build.
mathjax_path = 'mathjax/tex-chtml-full.js'

Here is my solve by edit the ext/mathjax.py file.
tested by edit the /usr/local/lib/python3.<n>/dist-packages/sphinx/ext/mathjax.py file, add lines from 83 line.
i.e., change

    if not app.config.mathjax_path:
        msg = 'mathjax_path config value must be set for the mathjax extension to work'
        raise ExtensionError(msg)

to

    if not app.config.mathjax_path:
        msg = 'mathjax_path config value must be set for the mathjax extension to work'
        raise ExtensionError(msg)
    else:
        if ( len(app.config.mathjax_path) > 4
             and app.config.mathjax_path[0:4] != 'http' # not a Url
             and app.config.mathjax_path[0] != '/'    # not absolute path inside DocumentRoot
        ):
            import os
            mathjax_abs_path = os.path.abspath(os.path.join(app.builder.outdir, '_static', app.config.mathjax_path))
            outdir_str_len = len(os.fspath(app.builder.outdir))
            if os.fspath(app.builder.outdir)+'/' != mathjax_abs_path[0:outdir_str_len+1] :
                print('\nPath is outside, and will be linked and changed to the inside.\n')
                filename = os.path.basename(mathjax_abs_path)
                TARGET = os.path.dirname(mathjax_abs_path)
                dirname = os.path.basename(TARGET)
                LINK_NAME = os.path.abspath(os.path.join(app.builder.outdir, '_static', dirname))
                print(LINK_NAME)
                os.system('ln -s -f '+TARGET+' '+LINK_NAME)
                app.config.mathjax_path = os.path.join(dirname, filename)

It works fine in my test, when just setting mathjax_path = '../../../../mathjax/_static/mathjax/tex-chtml-full.js' inside conf.py, and may need make clean; make html

it's just tested inside linux, may not be a good idea to push now.

[berlin2123]

mark as closed
Solutions Summary

Solution	Advantages	Disadvantages
copy files by html_static_path	auto copy files into DocumentRoot; just need to set the mathjax source	may use more storage. However, its just 11M per project, my be acceptable for not too many projects
link files by os.system inside conf.py	auto link files into DocumentRoot; link nearly do not use storage size	need to set the path/to/mathjax and path/to/build/html manually; only suitable for that the build path is not changed frequently
using a self-hosted mathjax webserver	do not use more storage	If the mathjax webserver is unstable, it may cause math to not work properly. I.e. it is not fully guaranteed that the project can be used completely independently.
edit source code of ext/mathjax.py	auto link; just need to set the mathjax source	just tested inside Linux server right now

[berlin2123]

Other solutions are welcomed!

[berlin2123]

Solved by adding a feature to create a symlink: #12080

After merged of this pull request, one can set conf.py as:

html_link_path = ['../../mathjax/_static/mathjax']    #  relative to configuration directory
mathjax_path = '_DoNotEditHerein/mathjax/tex-chtml-full.js'

or

html_link_path = [ ['../../mathjax/es5', '_static/_DoNotEditHerein/mathjax']  ]
mathjax_path = '_DoNotEditHerein/mathjax/tex-chtml-full.js'