Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support inline math with dollar $...$ delimiters when --config latex_math=True #410

Open
paloha opened this issue Oct 18, 2022 · 0 comments
Labels
enhancement New feature or request Hacktoberfest https://hacktoberfest.digitalocean.com

Comments

@paloha
Copy link

paloha commented Oct 18, 2022

Expected Behavior

Inline math delimited with $ ... $ should work in html output out of the box with --config latex_math=True specified.
It is supported in pandoc (link), GitHub (link), and finally it is being rolled out in GitLab (link) (this behavior still under-documented in official docs though). I create this issue based on @kernc reply in #28 (comment).

This unification is important, because users will be saved from the frustration when they are trying to display their math on multiple places, such as GitHub readme, GitLab readme, pdoc3 HTML, pdoc3 + pandoc PDF output, ...

Actual Behavior

Currently, the dollar delimiter style works only for blocks of math with $$...$$.

Steps to Reproduce

Steps for Ubuntu

  1. mkdir tmp
  2. virtualenv .venv
  3. pip install pdoc3
  4. source .venv/bin/activate
  5. nano test.py, paste the code from bellow and save the file
  6. run pdoc test.py --html --force --config latex_math=True
  7. go to html folder and open test.html in your browser
  8. if you wish, you can also generate and check the pdf output with:
    pdoc test.py --pdf | pandoc --metadata=title:"test" --from=markdown+abbreviations+tex_math_dollars --pdf-engine=xelatex --output=tmp.pdf
"""
This style of inline math delimited with 'brackets' works and should continue working \(\mathcal{O}(N)\).

This style of inline math delimited with 'dollars' should work $\mathcal{O}(N)$.

Escaping \$ should work in math like $X = \$3.25$ once it is implemented.

Blocks of math are already supported with the \$ delimiter and should stay so:
$$
\mathcal{O}(N) \\
X = \$3.25
$$

Blocks of math delimited with 'brackets' style are supported and should stay so:
\[
\mathcal{O}(N) \\
X = \$3.25
\]

Numbered blocks seem not to be supported and would be great if they would be.
The equation number now just jumpt to a new line like standard text:
$$
\mathcal{O}(N) \\
X = \$3.25
$$ (1)

\[
\mathcal{O}(N) \\
X = \$3.25
\] (1)

Line break in math blocks with two backslashes does not work. It seems MathJax includes this in v4.0.0-alpha.1.
https://github.com/mathjax/MathJax/issues/2312#issuecomment-1264672050
"""

You should get this HTML output:
image

You should get this PDF output:
image

Additional info

  • pdoc version: 0.10.0 and bellow

For those who want a workaround: Copy the head.mako from .venv/lib/python3.8/site-packages/pdoc/templates to your desired location, fill it with code from this answer, and then compile your documentation with custom --template-dir as @kernc suggested #28 (comment).

@kernc kernc added enhancement New feature or request Hacktoberfest https://hacktoberfest.digitalocean.com labels Oct 18, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request Hacktoberfest https://hacktoberfest.digitalocean.com
Development

No branches or pull requests

2 participants