sympy
sympy copied to clipboard
sympy
Change single backticks in Sphinx to render as code
Right now single backticks, like `this` in a docstring render as math. You need double backticks like ``this`` to render as code.
This confuses just about everyone because it's different from markdown, which is what GitHub uses for comments and so on.
Apparently you can set the single backticks to anything. I think the mathjax extension just sets it to math by default.
We do have a decent amount of math in our docstrings, but you can also use :math:`math`. I wonder if it would also be possible to make it use dollar signs. I suspect for every docstring currently using single backquotes for math there are two using it incorrectly for code.
Yup a lot of places make use of single and double backticks inconsistently. Add 'Easy to Fix'?
Well first we should discuss if we actually want to do this.
Also I don't know how easy this is to fix, since it requires modifying the Sphinx configuration. Hopefully it's not too hard, though.
This confuses just about everyone because it's different from markdown
More important, probably, that this break numpy docstring standard. Using single backticks required to enclose variables, e.g. in Parameters section.
I think the mathjax extension just sets it to math by default.
It's not mathjax, it's sympy devs (default_role sphinx option).
Changing the role of single backticks is easy to do in Sphinx config file, but I think that should be done only if single dollars can be used for inline math. MathJax can be configured to do that; in fact, this is in its config/default.js file:
inlineMath: [
// ['$','$'], // uncomment this for standard TeX math delimiters
['\\(','\\)']
],
The hard part is making the MathJax server use the modified configuration. It is not necessary to completely replace the standard combined configuration file (TeX-AMS-HTML-full); it will suffice to add a small local file to the config list provided the server can access it. That can apparently be arranged in two ways, either having the file locally on the server location or having it at some publicly accessible URL. There is already a skeleton local config file that does nothing. We could prepare a similar file local/inline-math.js for inline math. Our problem would then be solved if that could be placed at some public location. It could even be possible to have it at cdn.mathjax.org since we would certainly not be the only ones interested in it.
It might be simpler to use a Sphinx extension to convert $math$ to the appropriate inline math directive.
For example https://github.com/certik/sphinx-jax/blob/master/exts/math_dollar.py (CC @certik)
I agree, I think `this` should render code, and $ can render math. One can use the extension, that seems to work pretty well.
Should I change `this` to render code and $this$ to render math part in matrices.py docstring ?
The change here will need to happen in all modules at once when we make it, as it would change a single backtick to do code everywhere.
Since it will be a lot of work to change all single backticks throughout the code, a good first step would be to add the ability to use $math$, without messing with backticks just yet. Then we can transition over a few PRs instead of trying to do it all in one.
Ok so we pass every module from that extension and then every math part will be changed to $math$ . can we also use https://regexr.com/ for that
@asmeurer I have gone through extension code. So how can I help (what is my task) ? @certik https://github.com/certik/sphinx-jax/blob/master/exts/math_dollar.py#L36 I didn't understood this ?
@vishalg2235 I tried to document this part here:
https://github.com/certik/sphinx-jax/blob/master/exts/math_dollar.py#L15
There is an example there ($f(n) = 0 \text{ if $n$ is prime}$) where you don't want to change the inner $n$ into math, since mathjax or latex themselves will do that. So then the comment here:
https://github.com/certik/sphinx-jax/blob/master/exts/math_dollar.py#L27
explains that you substitute $n$ for a temporary string, then convert the rest of dollar signs to math, and then substitute back.
@vishalg2235 let me know if it is clear, and then once it is, can you please improve the documentation and comments in the code using your own words so that it's clear to others as well? That would be very helpful.
Besides backticks vs dollar, using latex in docstring - probably a bad idea in general (except for optional sections like suggested by numpy standard, e.g. Notes).
Yeah, I agree, I think it's best is to keep latex to minimum for docstrings.
I like the use of LaTeX math. It makes docstrings like the ones in the integral transforms docs easier to read. And even for small things, I think using LaTeX makes the docs look more professional. I think most people consume the SymPy documentation online.
Even for those that use ?, I think most people use the notebook. It is possible to render docstrings as html in the notebook. Unfortunately, it doesn't yet support LaTeX math. It also isn't enabled by default. So we should work with the IPython guys to get that fixed. But when we do the docs will render nicely with LaTeX math for almost everyone.
The main downside to too much LaTeX is for those of us who primarily look at docstrings in the terminal, or in the SymPy sources (myself included). It may actually be possible to extend the above docrepr idea to the terminal IPython so that ? opens the docstring in the browser.
Regardless, I think we should primarily focus on the majority of users, who use the html docs or the notebook.
I meant especially things like like $f(n) = 0 \text{ if $n$ is prime}$, which looks complicated, i.e., I think we should use rest or markdown to do the formatting, not latex. A simple latex math, like the one used in the integrals page, is fine I think.
It is possible to render docstrings as html in the notebook. Unfortunately, it doesn't yet support LaTeX math.
numpy docstring from example seems to be too ugly even without LaTeX rendering. Yet this feature looks promising.
But when we do the docs will render nicely with LaTeX math for almost everyone.
For Diofant, I'm thinking about using unicode pretty-printing for math, e.g. for above integral transform definitions (except for optional heavy-math sections). This should work both for sphinx docs and in any Jupyter frontend. (Or even in plain CPython console.)
I would also vote for moving most, if not all, latex into the "Notes" section of the docstrings. The main portion of the docstrings should be readable in ascii or unicode. I, for example, almost exclusively read SymPy doc strings in the terminal or notebook which only show the ascii/unicode. We followed this pattern in the mechanics package and the balance works pretty good. You can understand the docstrings when working interactively and look up the rendered versions if you want to know more details. The primary use of the docstring is to figure out quickly what to type as arguments to a method/function. The first lines of the docstring should reflect this.
If you want to refactor our docstrings, go for it. It's a separate question of whether we should use ` for code and $ for math, which I assume we all agree on.
@certik Ok I got that.. I'm getting an idea what math_dollar.py is doing. Still I don't understand many lines because regular expressions is new to me. I can improve documentation and comments in code. So should I send a PR in sphinx_jax repository ?
also while checking $...$ why we need r"(?<!$)(?<!\)$([^$]+?)$" in Line 41 . What is it doing
I suggest a multi-stage process for changing this:
- Make $math$ work for inline math.
- Change
default_roleto "error" and modify all the warnings to use double backticks if they should be code or dollar signs if they should be math. The recently added--keep-goingflag to Sphinx should help with this. - Do a mass find and replace of all double backticks with single backticks. Double backticks will continue to work, but single backticks will be preferred.
Step 1 can and should be done as a separate pull request.
The default_role="error" should only be done to find and replace, not merged into master. Steps 2 and 3 can be done in the same PR.
The idea is that there are a lot of misuses of single backticks still in the codebase that should be double backticks, so we should do an audit first to fix them all. We know that audit will be complete if they are all replaced with double backticks or dollar signs, which shouldn't be in error (hence the default_role="error").
As a side note, let's discuss whether or not LaTeX should be used at #14964, and not do any mass changes as part of this issue.
Oh now that I played with it I'm not sure if default_role="error" works like I thought it would. I thought it would error whenever it came across a default role (single backticks), but it actually seems to just error unconditionally on the first file. So we will need to find some other method of finding and removing all the default roles.
I tried using
mathjax_config = {
'tex2jax': {
'inlineMath': [ ['$','$']],
'displayMath': [ ['$$','$$']],
},
}
But it requires all backslashes to be escaped twice, like $\\sin(x)$. Otherwise Sphinx removes the backslash entirely. I'm not sure why it happens, if it is because of something we are doing or if it is from Sphinx itself.
I tested in a skeleton Sphinx build generated from sphinx-autogen and it strips the blackslashes there too. I also noticed that if you don't include a normal .. math directive somewhere, it doesn't load the MathJax Javascript on the page.
I asked about this on StackOverflow https://stackoverflow.com/questions/57813865/how-to-configure-sphinx-with-mathjax-to-use-dollar-signs-for-math-delimiter. Probably we can work around these issues using a custom extension similar to Ondřej's math_dollar.py, but I want to know if there is a better way (math_dollar.py can't be used directly, btw, because it just converts dollar signs to `, which we want to avoid).
But it requires all backslashes to be escaped twice
That seems to be a property of rst. However, according to this, it should be possible to use raw docstrings with single backslashes.