Formulas in pdoc

[igordertigor]

I really like pdoc and I'm considering to use it for a machine learning project. Yet, with machine learning documentation it is often useful to also include formulas in some places. Are there plans to allow for mathematical equations in pdoc any time soon? Or does pdoc even support equations already and I just didn't see it?

[igordertigor]

I feel that a simple way to solve this would be to include the following in pdoc/templates/html.mako line 455:

<script type="text/javascript" async src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML"> </script>

This way, the resulting html file would support mathjax style formulas. I can send a patch if desired.

[BurntSushi]

pdoc interprets doc strings as Markdown. That's the extent of formatting done.

I'm not keen on maintaining support for formula formatting in pdoc proper. I think it is a useful but niche feature. This is one of the reasons why I separated out the templates from core pdoc so that they could be customized downstream. I admit that this didn't work out as well as I'd hoped, since the view logic is quite complex and likely to be changed/tweaked over time.

You could add this yourself by copying html.mako and modifying it to support formula formatting. pdoc can then be configured to use your custom template.

[igordertigor]

Thank you, that sounds like a good option.

[cortesi]

Please see #153 for a unified discussion ticket about docstring flavors.