Sphinx: Math Rendering with Search Highlight

[ax3l]

Subject: Math rendering breaks with hightlighting

Problem

if you search for a keyword in a math formula, it interferes with rendering of the formula:

See e.g.

https://picongpu.readthedocs.io/en/latest/usage/workflows/laserPeakOnTarget.html?highlight=laser

vs.

https://picongpu.readthedocs.io/en/latest/usage/workflows/laserPeakOnTarget.html

cc @psychocoderHPC (initial report)

Procedure to reproduce the problem

See the links above :-)

Error logs / results

N/A

Expected results

Still render the math formula correctly even with highlight.

Reproducible project / your project

see above.

Source code: https://github.com/ComputationalRadiationPhysics/picongpu/blob/dev/docs/source/usage/workflows/laserPeakOnTarget.rst

Math extension: sphinx.ext.mathjax

• https://github.com/ComputationalRadiationPhysics/picongpu/blob/dev/docs/source/conf.py
• https://github.com/ComputationalRadiationPhysics/picongpu/blob/dev/docs/requirements.txt

Environment info

• OS: Linux on RTD
• Python version: 3.5
• Sphinx version: 1.7.1
• Browser for links above, tested with Firefox 59.0.1 (64-bit)

[jfbu]

This can be fixed using

diff --git a/sphinx/themes/basic/static/doctools.js_t b/sphinx/themes/basic/static/doctools.js_t
index b261a44f3..3df8c6c31 100644
--- a/sphinx/themes/basic/static/doctools.js_t
+++ b/sphinx/themes/basic/static/doctools.js_t
@@ -70,7 +70,7 @@ jQuery.fn.highlightText = function(text, className) {
     if (node.nodeType === 3) {
       var val = node.nodeValue;
       var pos = val.toLowerCase().indexOf(text);
-      if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) {
+      if (pos >= 0 && !jQuery(node.parentNode).hasClass(className) && !jQuery(node.parentNode).hasClass("math")) {
         var span;
         var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
         if (isInSVG) {

But better would be to highlight inside MathJax. This appears to be possible if one inserts via js this mark-up:

\color{#C00}{highlighted element}

I picked #C00 because the #fbe54e from basic.css for background color isn't very legible as text color, and I don't know if MathJax offers a possibility for background color. I fear a bit that injecting this \color will not be robust against search terms mixing letters and latex mark-up... so perhaps first measure would be to apply above patch because indeed the <span> tags added by the highlighter break MathJax.

[jfbu]

Ah, ok I did not know bbox MathJax extension so the correct fix is to get javascript to modify document mark-up into something like

\bbox[#fbe54e]{laser}

in order to highlight search results also in math blocks.

[tk0miya]

Fixed by #4844
Thank you for reporting!

[ax3l]

Thank you so much for the fix, this is wonderful! :sparkles: