Replace $...$ in docstrings by `...`

[Matthias Köppe]

A few files still use $...$ for math instead of backticks in docstrings.

We can make the source more uniform by replacing it.

In follow-up tickets, the function sage.misc.sagedoc.process_dollars (which is used in sage_docbuild.conf) will be deprecated (#33973) and eventually removed.

[Matthias Köppe]

New commits:

​4c0e7d7	sage.algebras: Replace $...$ in docstrings by `...`
​7b6016f	sage.calculus: Replace $...$ in docstrings by `...`
​6e2d614	sage.categories, coding, databases: Replace $...$ in docstrings by `...`

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​f0f707b

sage.geometry: Replace $...$ in docstrings by `...`

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​03895c0	sage.topology: Replace $...$ in docstrings by `...`
​9715f3f	sage.symbolic: Replace $...$ in docstrings by `...`
​73ce3e3	sage.structure: Replace $...$ in docstrings by `...`

[Travis Scrimshaw]

Yay. It will be good to be rid of these. Although it seems like there are a few changes missing, e.g.,

src/sage/algebras/steenrod/steenrod_algebra_mult.py

@@ -327 +327 @@
 
     None if the multinomial coefficient is 0, or sum of list if it is 1
 
-    Given the input $[n_1, n_2, n_3, ...]$, this computes the
+    Given the input `[n_1, n_2, n_3, ...]`, this computes the
     multinomial coefficient $(n_1 + n_2 + n_3 + ...)! / (n_1! n_2!
     n_3! ...)$, mod 2.  The method is roughly this: expand each
-    $n_i$ in binary.  If there is a 1 in the same digit for any $n_i$
-    and $n_j$ with $i\neq j$, then the coefficient is 0; otherwise, it
+    `n_i` in binary.  If there is a 1 in the same digit for any `n_i`
+    and `n_j` with `i\neq j`, then the coefficient is 0; otherwise, it
     is 1.
 
     EXAMPLES::
@@ -387 +387 @@
     a pair of tuples, as for r and s, and 'coeff' is an integer mod p.
 
     This computes the product of the Milnor basis elements
-    $Q_{e_1} Q_{e_2} ... P(r_1, r_2, ...)$ and
-    $Q_{f_1} Q_{f_2} ... P(s_1, s_2, ...)$.
+    `Q_{e_1} Q_{e_2} ... P(r_1, r_2, ...)` and
+    `Q_{f_1} Q_{f_2} ... P(s_1, s_2, ...)`.
 
     EXAMPLES::
 
@@ -578 +578 @@
 
     Associated multinomial coefficient, mod p
 
-    Given the input $[n_1, n_2, n_3, ...]$, this computes the
+    Given the input `[n_1, n_2, n_3, ...]`, this computes the
     multinomial coefficient $(n_1 + n_2 + n_3 + ...)! / (n_1! n_2!
-    n_3! ...)$, mod $p$.  The method is this: expand each $n_i$ in
-    base $p$: $n_i = \sum_j p^j n_{ij}$.  Do the same for the sum of
-    the $n_i$'s, which we call $m$: $m = \sum_j p^j m_j$.  Then the
-    multinomial coefficient is congruent, mod $p$, to the product of
-    the multinomial coefficients $m_j! / (n_{1j}! n_{2j}! ...)$.
+    n_3! ...)`, mod `p`.  The method is this: expand each `n_i` in
+    base `p`: `n_i = \sum_j p^j n_{ij}`.  Do the same for the sum of
+    the `n_i`'s, which we call `m`: `m = \sum_j p^j m_j`.  Then the
+    multinomial coefficient is congruent, mod `p`, to the product of
+    the multinomial coefficients `m_j! / (n_{1j}! n_{2j}! ...)`.
 
-    Furthermore, any multinomial coefficient $m! / (n_1! n_2! ...)$
+    Furthermore, any multinomial coefficient `m! / (n_1! n_2! ...)`
     can be computed as a product of binomial coefficients: it equals
 
     .. MATH::

Note the pairs split over multiple lines.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​cdb74b4

src/sage/algebras/steenrod/steenrod_algebra_mult.py: Replace $...$ in docstrings by `...` (fixup)

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​8cfdab1

sage.schemes: Replace $...$ in docstrings by `...`

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​b215c7e

sage.rings: Replace $...$ in docstrings by `...`

[Kwankyu Lee]

I did (tedious!) manual check in the rendered manual. All looks good except the following typos (not new) found in the touched lines.

Enclose v:

src/sage/categories/coxeter_groups.py

@@ -2744 +2744 @@
             OUTPUT:
 
             The unique Bruhat-maximum element ``x`` in ``W`` such that ``x W' = w W'``
-            and ``v $\ge$ ``x``.
+            and ``v `\ge` ``x``.

Remove is:

src/sage/categories/examples/semigroups_cython.pyx

@@ -151 +151 @@
         sage: S.some_elements()
         [3, 42, 'a', 3.4, 'raton laveur']
 
-    with product rule is given by $a \times b = a$ for all $a,b$. ::
+    with product rule is given by `a \times b = a` for all `a,b`. ::
 
         sage: S('hello') * S('world')

Single \:

src/sage/coding/guava.py

@@ -62 +62 @@
         sage: C = codes.QuasiQuadraticResidueCode(11); C   # optional - gap_packages (Guava package)
         [22, 11] linear code over GF(2)
 
-    These are self-orthogonal in general and self-dual when $p \\equiv 3 \\pmod 4$.
+    These are self-orthogonal in general and self-dual when `p \\equiv 3 \\pmod 4`.
 
     AUTHOR: David Joyner (11-2005)

\ before sin:

src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py

@@ -823 +823 @@
 
         ALGORITHM:
 
-        The operator of rotation over $\pi/2$ is $J^i_j = g^{ik}\omega_{jk}$,
-        where $\omega$ is the area form.  The operator of rotation over an
-        angle $\theta$ is $\cos(\theta) I + sin(\theta) J$.
+        The operator of rotation over `\pi/2` is `J^i_j = g^{ik}\omega_{jk}`,
+        where `\omega` is the area form.  The operator of rotation over an
+        angle `\theta` is `\cos(\theta) I + sin(\theta) J`.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​8e34f34

Reviewer fixes to docstrings

[Matthias Köppe]

Thanks a lot, done!

[John Palmieri]

Here are a few more:

src/sage/geometry/lattice_polytope.py

@@ -4263 +4263 @@
     `\overline{N} = N \times \ZZ^k` are dual lattices.
 
     The **Cayley polytope** `P \subset \overline{M}_\RR` of a nef-partition is
-    given by $P = \mathrm{Conv}(\Delta_0 \times e_0, \Delta_1 \times e_1,
+    given by `P = \mathrm{Conv}(\Delta_0 \times e_0, \Delta_1 \times e_1,
     \ldots, \Delta_{k-1} \times e_{k-1})`, where `\{e_i\}_{i=0}^{k-1}` is the
     standard basis of `\ZZ^k`. The **dual Cayley polytope**
     `P^* \subset \overline{N}_\RR` is the Cayley polytope of the dual

src/sage/groups/matrix_gps/isometries.py

@@ -1 +1 @@
 r"""
 Groups of isometries.
 
-Let `M = \ZZ^n` or `\QQ^n`, `b: M \times M \rightarrow \QQ$ a bilinear form and
-$f: M \rightarrow M$ a linear map. We say that $f$ is an isometry if for all
-elements $x,y$ of $M$ we have that $b(x,y)=b(f(x),f(y))$.
-A group of isometries is a subgroup of $GL(M)$ consisting of isometries.
+Let `M = \ZZ^n` or `\QQ^n`, `b: M \times M \rightarrow \QQ` a bilinear form and
+`f: M \rightarrow M` a linear map. We say that `f` is an isometry if for all
+elements `x,y` of `M` we have that `b(x,y)=b(f(x),f(y))`.
+A group of isometries is a subgroup of `GL(M)` consisting of isometries.
 
 EXAMPLES::
 

src/sage/schemes/toric/morphism.py

@@ -231 +231 @@
 So we see that the fiber over this point is an affine line. Together
 with another affine line in the other coordinate patch, this covers
 the exceptional `\mathbb{P}^1` of the blowup `O_{\mathbb{P}^1}(2) \to
-\CC^2/\ZZ_2$.
+\CC^2/\ZZ_2`.
 
 Here is an example with higher dimensional varieties involved::
 

After fixing these, if I make process_dollars(s) just return s, then the documentation builds successfully.

[Matthias Köppe]

Thanks! Could you push these changes to the ticket please?

[Matthias Köppe]

Replying to jhpalmieri:

After fixing these, if I make process_dollars(s) just return s, then the documentation builds successfully.

Thanks a lot for testing this. Probably we should keep process_dollars for now though because the docbuilding machinery may be in use in user packages. Perhaps we can emit a deprecation warning when process_dollars actually makes a substitution?

[John Palmieri]

I will push in a little bit; I've found at least one more change. I agree about process_dollars — I was just making that change to test things out. We can deprecate it on another ticket.

[John Palmieri]

Now the html and pdf docs build for me after essentially disabling process_dollars.

---

New commits:

​afa5bed

trac 33968: more changes

[Kwankyu Lee]

LGTM in rendered documentation.

[Matthias Köppe]

Thanks all!