change dollar signs to backticks

[jhpalmieri]

In a discussion on sage-devel, people thought it was a good idea to allow the use of dollar signs, not just backquotes, to delimit math in Sage docstrings. The attached patch does this. It does this by working with the autodoc extension to Sphinx: autodoc reads the docstring, which then gets processed by the new function process_dollars, which does various regular expression search-and-replacements.

Consequences of this: if you want to use a literal dollar sign in a docstring, you have to escape it with a backslash. If you have some complicated math with lots of nested math/text constructions like "\text{blah $x=y$ blah}", this might screw up. It will handle one nesting, turning

$f(x) = \text{zero if $x$ is prime}$

into

`f(x) = \text{zero if $x$ is prime}`

and leaving

`f(z) = \text{two if $z$ is an integer}`

unchanged; these should be processed correctly by both the html and pdf documentation builders.

The patch also changes some docstrings: either fixing minor misformattings which I noticed while testing this, or fixing things which break (like a docstring with a math environment with a missing closing dollar sign) when dollar signs are converted to backquotes.

Seems to work with Sphinx versions 0.5.1 (currently included in Sage) and 0.6.3 (see #6586).

Component: documentation

Author: John Palmieri

Reviewer: Mike Hansen

Merged: sage-4.2.alpha0

Issue created by migration from https://trac.sagemath.org/ticket/6892

[jhpalmieri]

Attachment: trac_6892-dollars.patch.gz

[dandrake]

minor rebase for 4.1.2.alpha1; tiny changes to conf.py and ambient_g0.py

[jhpalmieri]

Attachment: trac_6892-dollars-v2.patch.gz

Attachment: trac_6892-dollars-rebased.patch.gz

rebased against 4.1.2.alpha2, plus a little documentation

[jhpalmieri]

comment:1

Apply only trac_6892-dollars-rebased.patch. This adds a little documentation in the developer's guide about using dollar signs instead of backticks.

[mwhansen]

Reviewer: Mike Hansen

[mwhansen]

comment:2

Looks good to me.

[mwhansen]

Merged: sage-4.2.alpha0