BUG: LaTeX markers are being stripped from contents

[bashtage]

Code like \(R^{2}\) is being stripped from the LaTeX markers used by mathjax and so does not render correctly in the TOC or RHS contents.

It is also possible the <wbr> tokens being inserted would also cause problems even if the first issue is resolved.

[2bndy5]

We haven't really been actively supporting the latex builder in sphinx. Nonetheless, thanks for reporting this!

I suppose the nav_adapt.py could use some builder awareness as most of the ToC modifications are HTML builder oriented (ie the <wbr> insertions).

---

PS - This issue kinda links in to #56 since it concerns enhancements to nav_adapt.py.

[bashtage]

The code in the Contents section is

<a href="#r-2-calculation" class="md-nav__link">
 <span title="/panel/mathematical-formula.rst#r-2-calculation (reference label)" class="md-ellipsis">R^<wbr>{2} Calculation</span>
</a>

while in the main page it is

<h2 id="r-2-calculation">
<span class="math notranslate nohighlight">\(R^{2}\)</span> Calculation
<a class="headerlink" href="[#r-2-calculation](http://localhost:63342/linearmodels/doc/build/html/panel/mathematical-formula.html#r-2-calculation)" title="Permalink to this heading"></a>
</h2>

[bashtage]

This is only using the HTML builder. I don't use the LaTeX builder. The source is a standard RST file, and the relevant section title is

:math:`R^{2}` Calculation
-------------------------

[2bndy5]

My mistake. This seems like a duplicate of #56 then yes?

[jbms]

Currently the section titles are indeed converted to plain text for use in the toc / nav panels. That was intentional, because it seemed to me that styles intended for section headings, like literals shown in monospace font, might not display nicely in the toc. It also matched the behavior of mkdocs material at the time. However, as per #56 that may not always be desired. We haven't yet figured out the best alternative behavior, though.

[bashtage]

Seems to be related but different. Here there are <wbr> being liberally inserted, but the failure to render is due to stripping \( and \) around LaTeX blocks, which are there to be picked up by MathJAX.

[jbms]

The stripping of the mathjax markers is probably just happening via the call to astext():

sphinx-immaterial/sphinx_immaterial/nav_adapt.py

Line 258 in ff1f9bb

return str(markupsafe.Markup.escape("".join(x.astext() for x in node)))

[bashtage]

Not sure if this would be a dream or a nightmare - anyway to add an option to allow select tags/structures to skipped from conversion in conf.py?

[jbms]

Yeah I think customization along those lines could make sense. We'd have to figure out the details of exactly how to do it, though. Currently the text conversion happens on the docutils element tree. We could do various transformations of it, but the HTML translator code in Sphinx expects certain structure, and might break if we replace arbitrary nodes with text. Those issues might not occur too often in practice, though.

[2bndy5]

I took yet another swing at #56 and was able to get roles to render as expected, however, the render_partial()["fragment"] seems to add a paragraph for the :math: role (which apparently corrupts the nav structure for a page when used in the page heading).
If the math role is not the first node in the heading, then it works fine (🤷🏼‍♂️)

! :math:`R^{2}` this works
---------------------------

:math:`R^{2}` this doesn't
--------------------------

So, I essentially just just re-implemented the _inject_wbr() on only docutils.nodes.Text nodes which coincidentally works for inline literals and long-winded API names. My experimental changes are in the nav-roles branch if interested.

[2bndy5]

This also might be easier to do with MathML because mathjax isn't loaded for pages whose main content don't use it, regardless of :math: usage in the nav menus because nav_adapt.py is very different from normal sphinx themes' behavior. This also needs to account for the metadata title (used in the browsers' tab/window title).