Latex in doc strings

[matthew-hennefarth]

It would be nice to be able to write latex equations in the doc strings for functions. Adding a header html file such as

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.css"
      integrity="sha384-9eLZqc9ds8eNjO3TmqPeYcDj8n+Qfa4nuSiGYa6DjLNcv9BtN69ZIulL9+8CqC9Y" crossOrigin="anonymous">
<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.js"
        integrity="sha384-K3vbOmF2BtaVai+Qk37uypf7VrgBubhQreNQe9aGsz9lB63dIFiQVlJbr92dw2Lx"
        crossOrigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/contrib/auto-render.min.js"
        integrity="sha384-kmZOZB5ObwgQnS/DuDg6TScgOiWWBiVt0plIRkZCmE6rDZGrEOQeHM5PcHi+nyqe"
        crossOrigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function () {
        renderMathInElement(document.body, {
            delimiters: [
                {left: "$$", right: "$$", display: true},
                {left: "\\(", right: "\\)", display: false},
                {left: "$", right: "$", display: false},
                {left: "\\[", right: "\\]", display: true}
            ]
        });
    });
</script>

would enable this. See also the puruspe repo for an example.

[matthew-hennefarth]

This post seems like an interesting approach. Of course, downsides are that docs will require JavaScript. And will not longer be fully compatible in offline mode.

[SpookyYomo]

What would it take to locally validate that the LaTeX we write in documentation is indeed correct? Just don't want to make git log --graph more messy than it already is with commits just being docstrings.

[matthew-hennefarth]

What would it take to locally validate that the LaTeX we write in documentation is indeed correct?

I am not actually sure. Playing around with it, if I miss type something in a doc string like

$\pip$

or

$\end$

It will end up just rendering it directly as $\pip$ and $\end$. And the docs won't generate an error. I believe the issue is that the resulting HTML is no modified from the docstring itself, its only when its finally be rendered in the browser that it compiles it with KaTex.

Another approach could be to sparingly use Latex and only embed necessary equations as images that are pre-compiled first.

[matthew-hennefarth]

To remedy the offline issue, we can also consider the approach Scipy takes which is to have a local, stripped down version of MathJax. They then add a line in the header html that looks like:

<script async="async" src="../../_static/scipy-mathjax/MathJax.js?config=scipy-mathjax"></script>

This still doesn't fix the issue with verifying latex in docs are rendered correctly.