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

[mkoeppe]

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.

CC: @tscrim @kwankyu @jhpalmieri @tobiasdiez

Component: documentation

Author: Matthias Koeppe, John Palmieri

Branch/Commit: afa5bed

Reviewer: Kwankyu Lee, Travis Scrimshaw

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

[mkoeppe]

Branch: u/mkoeppe/replace___in_docstrings_by__

[mkoeppe]

Commit: 6e2d614

[mkoeppe]

Author: Matthias Koeppe

[mkoeppe]

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

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 6e2d614 to f0f707b

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

f0f707b

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

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from f0f707b to 73ce3e3

[tscrim]

comment:5

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

diff --git a/src/sage/algebras/steenrod/steenrod_algebra_mult.py b/src/sage/algebras/steenrod/steenrod_algebra_mult.py
index e2c1e88..0934c31 100644
--- a/src/sage/algebras/steenrod/steenrod_algebra_mult.py
+++ b/src/sage/algebras/steenrod/steenrod_algebra_mult.py
@@ -327,11 +327,11 @@ def multinomial(list):

     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,8 +387,8 @@ def milnor_multiplication_odd(m1,m2,p):
     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,15 +578,15 @@ def multinomial_odd(list,p):

     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.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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)

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 73ce3e3 to cdb74b4

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from cdb74b4 to 8cfdab1

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

8cfdab1

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

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 8cfdab1 to b215c7e

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

b215c7e

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

[kwankyu]

comment:9

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:

--- a/src/sage/categories/coxeter_groups.py
+++ b/src/sage/categories/coxeter_groups.py
@@ -2744,7 +2744,7 @@ class CoxeterGroups(Category_singleton):
             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:

--- a/src/sage/categories/examples/semigroups_cython.pyx
+++ b/src/sage/categories/examples/semigroups_cython.pyx
@@ -151,7 +151,7 @@ class LeftZeroSemigroup(LeftZeroSemigroupPython):
         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 \:

--- a/src/sage/coding/guava.py
+++ b/src/sage/coding/guava.py
@@ -62,7 +62,7 @@ def QuasiQuadraticResidueCode(p):
         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:

--- a/src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py
+++ b/src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py
@@ -823,9 +823,9 @@ class ParametrizedSurface3D(SageObject):

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

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

8e34f34

Reviewer fixes to docstrings

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from b215c7e to 8e34f34

[mkoeppe]

comment:11

Thanks a lot, done!

[jhpalmieri]

comment:12

Here are a few more:

diff --git a/src/sage/geometry/lattice_polytope.py b/src/sage/geometry/lattice_polytope.py
index 89a4e9a219..eba29281a7 100644
--- a/src/sage/geometry/lattice_polytope.py
+++ b/src/sage/geometry/lattice_polytope.py
@@ -4263,7 +4263,7 @@ class NefPartition(SageObject, Hashable):
     `\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
diff --git a/src/sage/groups/matrix_gps/isometries.py b/src/sage/groups/matrix_gps/isometries.py
index ab611b4ce7..f9111a2c92 100644
--- a/src/sage/groups/matrix_gps/isometries.py
+++ b/src/sage/groups/matrix_gps/isometries.py
@@ -1,10 +1,10 @@
 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::

diff --git a/src/sage/schemes/toric/morphism.py b/src/sage/schemes/toric/morphism.py
index ca5686eebe..75b683a41f 100644
--- a/src/sage/schemes/toric/morphism.py
+++ b/src/sage/schemes/toric/morphism.py
@@ -231,7 +231,7 @@ blow-up in this single coordinate chart. Lets investigate further::
 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.

[mkoeppe]

comment:13

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

[mkoeppe]

comment:14

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?

[jhpalmieri]

comment:15

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.

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,4 +1,7 @@
 A few files still use `$...$` for math instead of backticks in docstrings.

-We can make the source more uniform by replacing it. Then 
-the function `sage.misc.sagedoc.process_dollars` (which is used in `sage_docbuild.conf`) can be deprecated and eventually removed
+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.

[jhpalmieri]

Changed branch from u/mkoeppe/replace___in_docstrings_by__ to u/jhpalmieri/replace___in_docstrings_by__

[jhpalmieri]

Changed commit from 8e34f34 to afa5bed

[jhpalmieri]

comment:18

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

---

New commits:

afa5bed

trac 33968: more changes

[kwankyu]

Reviewer: Kwankyu Lee

[kwankyu]

comment:19

LGTM in rendered documentation.

[kwankyu]

Changed author from Matthias Koeppe to Matthias Koeppe, John Palmieri

[kwankyu]

Changed reviewer from Kwankyu Lee to Kwankyu Lee, Travis Scrimshaw

[mkoeppe]

comment:21

Thanks all!

[vbraun]

Changed branch from u/jhpalmieri/replace___in_docstrings_by__ to afa5bed