Mathematics in docstrings ?

[lmoresi]

We (@underworldcode) recently adopted pdoc3 for some of our pure python projects and we were wondering about the status of mathematical equations in the generated documentation.

We often include snippets of latex in our docstrings for cases where we are implementing something overtly mathematical that needs explaining and where an explanation that tries to skirt the equations is horribly convoluted.

An example here: http://www.underworldcode.org/stripy/cartesian.html#stripy.cartesian.Triangulation.interpolate_cubic. The docs in this case are from pdoc3 with a tweak to add mathjax headers and include the markdown mathematics extensions.

We'd be interested to know if this is a benign addition to pdoc3 that could ultimately be useful / optionally supported or if it is a niche case of little interest in real life.

[kernc]

This certainly should be supported. 👍 The preferred mechanism of MathJax inclusion and configuration is by overriding head.mako template. How else are you doing it?

[lmoresi]

Thanks for responding.

Over-riding the template is the first part, but there are two issues that caused me to raise this with the devs as a question.

The first is that it is helpful (but not essential) to add the "mdx_math" markdown extension that wraps all the math tags nicely but then adds a dependency not everyone needs - so I wasn't sure how you would approach that without hacking into the code.

The second is that latex uses \ in nearly every command and this triggers a lot of deprecated escape character warnings from pdoc3. This can be avoided by escaping all the backslashes and writing equations as $$\sin^2 \theta + \cos^2 \theta = 1$$ (that's what we did in our example docs linked above) but that looks weird to a latex person. The other way is to treat/mark all docstrings as raw. If we mark them as raw then no escapes are necessary, but the code looks weird to a python person. I don't know what side effects that has in more general pdoc3 usage or with docstrings as they appear in notebooks.

In other words, our modifications work for our very specific project and we don't have the experience to see if there are problems ahead. We thought pdoc3 was amazing - up and running in just a few minutes and with very clear coding style behind the scenes - so we'd like to adopt it as our default and decide on a "house-style" for our equation markup.

Thanks for your time.

L

[kernc]

Sorry for the late reply.

NumPy, SciPy, and scikit-learn, as some of the flagship, math-proponing Python projects, use either double escapes or raw strings, interchangeably. Neither choice affects pdoc3 in any way.

mdx_math is not a heavy dependency, but since it's indeed a single file that only does some regex-replaces, we could strip away the use of python-markdown extension API and just do some regex substitution magic early in the pipeline, as we already do for all other docformats anyway.

I think config.mako setting latex_math = False would be fine, and it would only support default MathJax delimiters: \( for inline and \[ or $$ for block equations.

If you have no objections, and unless you want to implement the feature yourself, I'll try to come up with something.

[kernc]

@lmoresi There's a PR to test in #74.

Running pdoc with -c latex_math=True command line option should be all that's required.

I prefer this approach to mdx_math, because the latter replaces verbatim math code with <script> tags, the content of which is hidden as long as JavaScript is disabled. only if preview is disabled.

[lmoresi]

See my comments on the PR. This is exactly what we want to achieve. And, yes, I think you are right that seeing the original latex snippets is a better solution if there is no javascript available.

Shall I leave this open while the PR is going through ?