search

sympy / sphinx-math-dollar

Sphinx extension to let you write LaTeX math using $$
https://www.sympy.org/sphinx-math-dollar/
MIT License
33 stars 11 forks source link

Does not render math in autosummary table #18

Open goerz opened 4 years ago

goerz commented 4 years ago

It seems that math is not rendered inside an autosummary table. That is, if the first line of a function docstring contains dollar-enclosed math, then having that function in an autosummary directive will result in table where the math is not rendered.

The math rendering works fine when displaying the entire function docstring via an automodule directive.

goerz commented 4 years ago

Blocks https://github.com/goerz/cookiecutter-pypackage/issues/14 (this is just so that I have this issue status shown there)

asmeurer commented 4 years ago

Sorry I didn't notice this earlier. This is probably just a question of modifying the node blacklist, which you can also do manually (see https://github.com/sympy/sphinx-math-dollar#configuration).

APN-Pucky commented 3 years ago

Thanks, excluding comment and paragraph from the blacklist worked for me.

from docutils.nodes import FixedTextElement, literal,math
from docutils.nodes import  comment, doctest_block, image, literal_block, math_block, paragraph, pending, raw, rubric, substitution_definition, target
math_dollar_node_blacklist = (literal,math,doctest_block, image, literal_block,  math_block,  pending,  raw,rubric, substitution_definition,target)
asmeurer commented 3 years ago

Is the problem that the node that you want to include math is a FixedTextElement?

Feel free to make a PR fixing the default blacklist in the code.

APN-Pucky commented 3 years ago

I think so. I just went through it by trial and error and apparently, in my case, comment and paragraph (which are FixedTextElements) caused autosummary to not display the math. I won't PR since I have no clue about side effects of this.

asmeurer commented 3 years ago

I picked FixedTextElement because it seemed like it was the superclass of the nodes that I wanted to avoid (like the doctest node). You can see all the nodes here https://github.com/docutils-mirror/docutils/blob/e88c5fb08d5cdfa8b4ac1020dd6f7177778d5990/docutils/nodes.py. One thing confuses me, which is that paragraph does not appear to be a FixedTextElement https://github.com/docutils-mirror/docutils/blob/e88c5fb08d5cdfa8b4ac1020dd6f7177778d5990/docutils/nodes.py#L1577. Perhaps this isn't actually related. Furthermore, Sphinx itself adds several nodes that are FixedTextElement, which appear to be the sort of thing that should be blacklisted https://github.com/sphinx-doc/sphinx/blob/cc7396501603fec57222084b2487768c54cbd93c/sphinx/addnodes.py.

If you build the docs with the default configuration and MATH_DOLLAR_DEBUG=1, it should output which nodes are skipped. Which nodes does it say are not being included? It only prints it for nodes that appear to have dollar math, so be sure to add some LaTeX somewhere where it isn't working.