Inline Math doesn't seem to support escapes with backslash

[Loitador41]

Problem Description

When using the inline Math syntax :math:, it doesn't seem to be possible to escape curly brackets or underscores with a backslash.

Steps to reproduce the behavior:

1. Create a file that contains the following code:

''':math:`\{x \\in R\_index \}`'''

2. Run the following command:
   pdoc file_directory --output-dir output_directory --math

System Information

pdoc: 12.1.0
Python: 3.9.12
Platform: Windows-10-10.0.19044-SP0

[mhils]

The problem here is that first Python, then our Markdown parser, and then MathJax tries to handle character escaping. Python's escaping does not change anything in this case here, but our Markdown parser converts \{ into { (as it should by convention) and then MathJax does not see any escaping. The workaround here is to add more backslashes:

r''':math:`\\{x \in R_{index} \\}`'''
# or:
''':math:`\\\\{x \\in R_{index} \\\\}`'''

We could presumably add a bit of code here that does additional escaping for math blocks before they get fed into markdown2. :)

pdoc/pdoc/docstrings.py

Lines 216 to 218 in e2b5930

	# Math: :math:`foo` -> \\( foo \\)
	# We don't use $ as that's not enabled by MathJax by default.
	contents = re.sub(r":math:`(.+?)`", r"\\\\( \1 \\\\)", contents)

pdoc/pdoc/docstrings.py

Lines 329 to 330 in e2b5930

	if type == "math":
	return f"{ind}$${val}{contents}$$\n"

https://github.com/trentm/python-markdown2/blob/3f6113438ce2e776310f7c6e3f0c5a8097aefb82/lib/markdown2.py#L128-L130

[thehappycheese]

Hi eveyone :)

I was trying to find a fix today, but I think I am stuck; As @mhils points out the issue is that markdown2 is working exactly as expected and treating \\ as an escaped \.

But there is also potentially something wierd going on in the image below where \\\\ is rendering as only one \ in html...

If that isnt the problem, then as far as I can tell the solution requires

1. Actually properly parsing the markdown and automatically adding extra \ inside $$...$$ blocks, and
2. User having to remember to use r-strings.

Unless there is another approach?

I produced the demo below that illustrates the problem.

Currently VS Code doesnt support mathjax in inline documentation popups

However it does treat backslashes correctly in markdown files (consistent with github markdown i think)