Comparison: sphinx.ext.imgmath vs sphinx-mathjax-offline

[yunchae-kim]

When improving our documentation setup for Comptox AI, we faced the decision of which Sphinx extension to use for math rendering. This issue provides a detailed comparison of sphinx.ext.imgmath and sphinx-mathjax-offline, which informed our decision.

sphinx.ext.imgmath:

• Method: Converts LaTeX math equations into images.
• Dependencies: Requires dvipng, dvisvgm, or convert (from ImageMagick) command to be on the system. This involves converting LaTeX to DVI and then to the desired image format.

Pros:

• No dependence on JavaScript: Renders equations as images, so no need for users to have JavaScript enabled.
• Provides a consistent appearance across all platforms and browsers.

Cons:

• Image rendering might not be as sharp on all devices or resolutions, especially compared to font-based methods.
• Results in larger documentation size due to the use of images.
• Less accessible to screen readers.
• Potential color discrepancies between the doc's background and the generated image.
• Requires a LaTeX installation when building on systems like our EC2 instance. This can be problematic given the memory limitations of our free-tier EC2 setup.

sphinx-mathjax-offline:

• Method: Utilizes the MathJax JavaScript library to render LaTeX math equations in browsers using an offline version of the library.
• Dependencies: None outside of the extension, as it includes a version of MathJax with the documentation.

Pros:

• Renders crisply: Uses web or local fonts for display, ensuring clear, scalable equations.
• Fully functional offline, unlike sphinx.ext.mathjax which retrieves MathJax from a CDN.
• More accessible to screen readers compared to image-based methods.

Cons:

• Requires JavaScript: Users must have JavaScript enabled in their browsers for proper rendering.
• Might increase page load times if there's a lot of mathematical content, due to browser processing.
• Potentially larger documentation size owing to bundled MathJax scripts.

Decision:
Given our specific requirements, especially concerning our EC2 setup and memory constraints, we opted to use sphinx-mathjax-offline. This decision prioritizes scalable rendering, offline capabilities, and avoids the necessity of a resource-heavy LaTeX installation on our EC2 instance.

Related issues: #87 , #101