Use katex_js_path when pre-rendering

[hagenw]

Relates to #122

This uses the value from katex_js_path for the path to the KaTeX executable, used inside katex-server.js to render the pages in pre-render mode. The default value of katex_js_path points to the KaTeX Javascript library bundled with this extension, but the user can point to another file on the local machine.

[hagenw]

@kalvdans can you take a look at the proposed changes, and check if this would work for you.

[kalvdans]

@kalvdans can you take a look at the proposed changes, and check if this would work for you.

I will check, give me an hour or two.

[kalvdans]

Thank you! The patch works out-of-the box for my usecase, pointing to the system-wide installation of katex.

Just commenting some minor comments on certain rows. Additional minor comments:

• The error handling is ugly when path doesn't exist. (says: Please also report this if it was a user error, so that a better error message can be provided next time.)

• "Relates to" can be changed to "Fixes" in the PR title (unless you want to keep the issue open until release)

[kalvdans]

Do not use capitals for variables.

Suggested change

	# Path to KaTeX javascript file
	KATEX_PATH = None
	# Path to KaTeX javascript file, or None if the bundled should be used.
	katex_path = None

[hagenw]

I changed all class variables of KaTeXServer to use lower case letters.

[hagenw]

• "Relates to" can be changed to "Fixes" in the PR title (unless you want to keep the issue open until release)

I only used "Relates" and not "Fixed" yet, as you were also concerned about katex.min.css, which I did not handle in this pull request. Should we still target to include it as well? I'm not sure if it is better for caching in the browser if the CSS file is always downloaded from the same server, and not from a different one for each documentation HTML page?

[kalvdans]

• "Relates to" can be changed to "Fixes" in the PR title (unless you want to keep the issue open until release)

I only used "Relates" and not "Fixed" yet, as you were also concerned about katex.min.css, which I did not handle in this pull request. Should we still target to include it as well? I'm not sure if it is better for caching in the browser if the CSS file is always downloaded from the same server, and not from a different one for each documentation HTML page?

I'm happy with the configurability of katex css, but let's discuss that further in the issue.

[kalvdans]

Turns our the relative path doesn't work in Ubuntu 22.04, only in Ubuntu 24.04.

Error: Cannot find module './../../../../../../usr/share/javascript/katex/katex'

strace shows it tries to open /home/usr/share/javascript/katex/katex.js even though no chdir has taken place. Manually running require('./../../../../../../usr/share/javascript/katex/katex') in a nodejs prompt works on both operating systems.

Ubuntu 22.04 have nodejs v12.22.9 while Ubuntu 24.04 have v18.19.1.

[hagenw]

Thanks for pointing this out. I will try to fix this tomorrow and add a test for it.

[hagenw]

Turns our the relative path doesn't work in Ubuntu 22.04, only in Ubuntu 24.04.

Error: Cannot find module './../../../../../../usr/share/javascript/katex/katex'

strace shows it tries to open /home/usr/share/javascript/katex/katex.js even though no chdir has taken place. Manually running require('./../../../../../../usr/share/javascript/katex/katex') in a nodejs prompt works on both operating systems.

Ubuntu 22.04 have nodejs v12.22.9 while Ubuntu 24.04 have v18.19.1.

I updated the code slightly and added a few tests for it, but it might be that there is no simple solution for cases in which the relative path fails for nodejs, compare https://blog.spencersnyder.io/solving-the-long-relative-paths-problem-natively-in-node-js-6aeebc3a81bd.

[kalvdans]

Turns our the relative path doesn't work in Ubuntu 22.04, only in Ubuntu 24.04.

Error: Cannot find module './../../../../../../usr/share/javascript/katex/katex'

The mystery is solved, turns out my current working directory when I tested on Ubuntu 24.04 was by luck exactly the same level deep as ~/env/lib/python3.12/site-packages/sphinxcontrib/.

I updated the code slightly and added a few tests for it

With your changes to make the path relative to SRC_DIR instead of current working directory it works fine for me. Our CI passes with the lastest version (bc0db1f5) of this PR. Thanks a lot for the fix!