Test latex equations

[danwos]

Looks very nice, but it seems to display the latex input instead of rending the equations (as intended by latex) ?
Sorry if you got two copies of this post, I was trying to fix a typo in the previous version.

Not sure which mechanism is used here.
Maybe it is really raw-latex code, then it would not be possible.

But if the author is using some of the HTML math extensions, it should work:
https://www.sphinx-doc.org/en/master/usage/extensions/math.html

But we should test and document it.

https://groups.google.com/g/sphinx-users/c/r4ahhcagNK0/m/PMZ9EDJYAQAJ

[btb]

Found the link for the discussion you're referring to: https://groups.google.com/g/sphinx-users/c/r4ahhcagNK0/m/PMZ9EDJYAQAJ

But that's not me.

[danwos]

Ohh ok, sorry, I remove your name from the issue. :/

[kreuzberger]

Ran into this issue with our local documentation. Currently there seems to be no native math implementation for html in sphinx, just with mathjax or rendering as image. Cause image rendering is not so good (e.g. due to zooming/scaling in some html viewers used to display documentation) a better solution should be provided.

As it seems to fully ship mathjax in the html build seems to be no good idea. to have it locally installed for the pdf builds seems ok.

Due to your knowledge: Is there any other (maybe simpler) solution available, maybe with another directive?

[kreuzberger]

Seems to be this could be solved by
jbms/sphinx-immaterial#251
in future.
See also sphinx-doc/sphinx#6092

[kreuzberger]

The MathJax package seems to be about ~ 25 MB large. So deploying for the build with any document is not helpful. For the simplepdf build it is ok to use a centralised version, cause no html gets delivered

[kreuzberger]

Using https://pypi.org/project/sphinx-mathjax-offline/ Math output is working for the html builder.
Simplepdf Builders seems not to add

<script async="async" src="_static/mathjax/tex-chtml.js"></script>

to the html
So adding manually in conf.py[.in]

mathjax_path = "mathjax/tex-chtml.js"
html_js_files = [
    mathjax_path
]

fixes the problem.

Generated HTML shows now proper math equations. But generated pdf does not.

[kreuzberger]

Finaly solved for me by adding / using

 extensions + =  'sphinx.ext.imgmath'
 imgmath_image_format = 'svg'

Math output is properly shown in html and could also be scaled properly in html, singlepagehtml and weasyprint pdf.

[kreuzberger]

diff --git a/demo/conf.py b/demo/conf.py
index 593ed26..557aafb 100644
--- a/demo/conf.py
+++ b/demo/conf.py
@@ -26,6 +26,8 @@ extensions = [
     'sphinxcontrib.plantuml',
     'sphinx_needs',
     'sphinx.ext.autodoc',
+    'sphinx.ext.imgmath',
+
 ]
 
 version = "1.0"  # Will not be raised
@@ -74,6 +76,7 @@ plantuml_output_format = "svg_img"
 local_plantuml_path = os.path.join(os.path.dirname(__file__), "../", "docs", "utils", "plantuml.jar")
 plantuml = f"java -Djava.awt.headless=true -jar {local_plantuml_path}"
 
+imgmath_image_format = 'svg'
 
 def setup_jquery(app, exception):
     """

[danwos]

Thanks for the investigation and the excellent report.

At least we should document this somewhere in the docs.

Do you think we should force the installation of sphinx.ext.imgmath and inject the needed configuration on our own when a simpledpdf build gets invoked?

[kreuzberger]

At least we should document this somewhere in the docs.

I think documentation would be necessary, also an example solution in the demo pdf

Do you think we should force the installation of sphinx.ext.imgmath and inject the needed configuration on our own when a simpledpdf build gets invoked?

I think not. Reasons for me are:

• the provided solution may not satisfy some poeple or they have already a solution with mathjax
• Regarding the issues sphinx itself will provide a better solution for html5 builds, so the extension would not be needed in future sphinx releases.

Documentation of the solution in the docs and demo config would be enough for me.

[rkdarst]

This was the fix for jupyter-book + mathjax:
https://github.com/executablebooks/jupyter-book/pull/1774/files
with the problem described in the opening issue:
jupyter-book/jupyter-book#1705

I guess a similar could apply here?

The solution from there was:

            # set the below flag to always to enable maths in singlehtml builder
            if app.builder.name == "singlehtml":
                app.set_html_assets_policy("always")

I haven't tried to do this yet, and I haven't even used simplepdf before (I came across this while checking for the solution in various builders), but thought it might help...