Opened 2 months ago

Closed 2 months ago

# Replace $...$ in docstrings by ...

Reported by: Owned by: mkoeppe major sage-9.7 documentation tscrim, klee, jhpalmieri, gh-tobiasdiez Matthias Koeppe, John Palmieri Kwankyu Lee, Travis Scrimshaw N/A afa5bed afa5bed0f784d25343cbf9c95a680e5af1a3a61c

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.

### comment:1 Changed 2 months ago by mkoeppe

• Branch set to u/mkoeppe/replace_______in_docstrings_by______

### comment:2 Changed 2 months ago by mkoeppe

• Authors set to Matthias Koeppe
• Commit set to 6e2d614510ae0c2236f041fbf0e3e0c4d1e5905d
• Status changed from new to needs_review

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

### comment:3 Changed 2 months ago by git

• Commit changed from 6e2d614510ae0c2236f041fbf0e3e0c4d1e5905d to f0f707b3c364cd2f64a530e56ca899deed18d4f1

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

 ​f0f707b sage.geometry: Replace $...$ in docstrings by ...

### comment:4 Changed 2 months ago by git

• Commit changed from f0f707b3c364cd2f64a530e56ca899deed18d4f1 to 73ce3e33e2a092bb16df2def931e3f60a8d30102

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

### comment:5 Changed 2 months ago by tscrim

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

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

### comment:6 Changed 2 months ago by git

• Commit changed from 73ce3e33e2a092bb16df2def931e3f60a8d30102 to cdb74b4273d3241bc62b00f1ea60049b52d7bfe0

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)

### comment:7 Changed 2 months ago by git

• Commit changed from cdb74b4273d3241bc62b00f1ea60049b52d7bfe0 to 8cfdab1e449b441d0bc957aa835e2a89508958b7

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

 ​8cfdab1 sage.schemes: Replace $...$ in docstrings by ...

### comment:8 Changed 2 months ago by git

• Commit changed from 8cfdab1e449b441d0bc957aa835e2a89508958b7 to b215c7e23bce4166d936c9dc8aec04959fde3e00

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

 ​b215c7e sage.rings: Replace $...$ in docstrings by ...

### comment:9 Changed 2 months ago by klee

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

 a 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:

• ## src/sage/categories/examples/semigroups_cython.pyx

 a 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 \:

• ## src/sage/coding/guava.py

 a 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:

• ## src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py

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

### comment:10 Changed 2 months ago by git

• Commit changed from b215c7e23bce4166d936c9dc8aec04959fde3e00 to 8e34f345233af19473f8b52afde5a398b5f08efc

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

 ​8e34f34 Reviewer fixes to docstrings

### comment:11 Changed 2 months ago by mkoeppe

Thanks a lot, done!

### comment:12 follow-up: ↓ 14 Changed 2 months ago by jhpalmieri

Here are a few more:

• ## src/sage/geometry/lattice_polytope.py

diff --git a/src/sage/geometry/lattice_polytope.py b/src/sage/geometry/lattice_polytope.py
index 89a4e9a219..eba29281a7 100644
• ## src/sage/schemes/toric/morphism.py

diff --git a/src/sage/schemes/toric/morphism.py b/src/sage/schemes/toric/morphism.py
index ca5686eebe..75b683a41f 100644
 a 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.

### comment:13 Changed 2 months ago by mkoeppe

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

### comment:14 in reply to: ↑ 12 Changed 2 months ago by mkoeppe

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?

### comment:15 Changed 2 months ago by jhpalmieri

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.

### comment:16 Changed 2 months ago by mkoeppe

• Description modified (diff)

### comment:17 Changed 2 months ago by jhpalmieri

• Branch changed from u/mkoeppe/replace_______in_docstrings_by______ to u/jhpalmieri/replace_______in_docstrings_by______

### comment:18 Changed 2 months ago by jhpalmieri

• Commit changed from 8e34f345233af19473f8b52afde5a398b5f08efc to afa5bed0f784d25343cbf9c95a680e5af1a3a61c

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

New commits:

 ​afa5bed trac 33968: more changes

### comment:19 Changed 2 months ago by klee

• Authors changed from Matthias Koeppe to Matthias Koeppe, John Palmieri
• Reviewers set to Kwankyu Lee
• Status changed from needs_review to positive_review

LGTM in rendered documentation.

### comment:20 Changed 2 months ago by klee

• Reviewers changed from Kwankyu Lee to Kwankyu Lee, Travis Scrimshaw

Thanks all!

### comment:22 Changed 2 months ago by vbraun

• Branch changed from u/jhpalmieri/replace_______in_docstrings_by______ to afa5bed0f784d25343cbf9c95a680e5af1a3a61c
• Resolution set to fixed
• Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.