Change single backticks in Sphinx to render as code

[asmeurer]

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.

[gxyd]

Yup a lot of places make use of single and double backticks inconsistently. Add 'Easy to Fix'?

[asmeurer]

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.

[skirpichev]

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).

[jksuom]

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.

[asmeurer]

It might be simpler to use a Sphinx extension to convert $math$ to the appropriate inline math directive.

[asmeurer]

For example https://github.com/certik/sphinx-jax/blob/master/exts/math_dollar.py (CC @certik)

[certik]

I agree, I think `this` should render code, and $ can render math. One can use the extension, that seems to work pretty well.

[vishalg2235]

Should I change `this` to render code and $this$ to render math part in matrices.py docstring ?

[asmeurer]

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.

[vishalg2235]

ok.. is there something that I could help ?

[asmeurer]

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.

[vishalg2235]

can you please guide me how to add that ability ?

[asmeurer]

We need to copy the Sphinx extension from @certik that I mentioned above.