Opened 2 months ago
Closed 2 months ago
#33968 closed enhancement (fixed)
Replace $...$ in docstrings by `...`
Reported by:  mkoeppe  Owned by:  

Priority:  major  Milestone:  sage9.7 
Component:  documentation  Keywords:  
Cc:  tscrim, klee, jhpalmieri, ghtobiasdiez  Merged in:  
Authors:  Matthias Koeppe, John Palmieri  Reviewers:  Kwankyu Lee, Travis Scrimshaw 
Report Upstream:  N/A  Work issues:  
Branch:  afa5bed (Commits, GitHub, GitLab)  Commit:  afa5bed0f784d25343cbf9c95a680e5af1a3a61c 
Dependencies:  Stopgaps: 
Description (last modified by )
A few files still use $...$
for math instead of backticks in docstrings.
We can make the source more uniform by replacing it.
In followup tickets,
the function sage.misc.sagedoc.process_dollars
(which is used in sage_docbuild.conf
) will be deprecated (#33973) and eventually removed.
Change History (22)
comment:1 Changed 2 months ago by
 Branch set to u/mkoeppe/replace_______in_docstrings_by______
comment:2 Changed 2 months ago by
 Commit set to 6e2d614510ae0c2236f041fbf0e3e0c4d1e5905d
 Status changed from new to needs_review
comment:3 Changed 2 months ago by
 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
 Commit changed from f0f707b3c364cd2f64a530e56ca899deed18d4f1 to 73ce3e33e2a092bb16df2def931e3f60a8d30102
comment:5 Changed 2 months ago by
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 b def multinomial(list): 327 327 328 328 None if the multinomial coefficient is 0, or sum of list if it is 1 329 329 330 Given the input $[n_1, n_2, n_3, ...]$, this computes the330 Given the input `[n_1, n_2, n_3, ...]`, this computes the 331 331 multinomial coefficient $(n_1 + n_2 + n_3 + ...)! / (n_1! n_2! 332 332 n_3! ...)$, mod 2. The method is roughly this: expand each 333 $n_i$ in binary. If there is a 1 in the same digit for any $n_i$334 and $n_j$ with $i\neq j$, then the coefficient is 0; otherwise, it333 `n_i` in binary. If there is a 1 in the same digit for any `n_i` 334 and `n_j` with `i\neq j`, then the coefficient is 0; otherwise, it 335 335 is 1. 336 336 337 337 EXAMPLES:: … … def milnor_multiplication_odd(m1,m2,p): 387 387 a pair of tuples, as for r and s, and 'coeff' is an integer mod p. 388 388 389 389 This computes the product of the Milnor basis elements 390 $Q_{e_1} Q_{e_2} ... P(r_1, r_2, ...)$and391 $Q_{f_1} Q_{f_2} ... P(s_1, s_2, ...)$.390 `Q_{e_1} Q_{e_2} ... P(r_1, r_2, ...)` and 391 `Q_{f_1} Q_{f_2} ... P(s_1, s_2, ...)`. 392 392 393 393 EXAMPLES:: 394 394 … … def multinomial_odd(list,p): 578 578 579 579 Associated multinomial coefficient, mod p 580 580 581 Given the input $[n_1, n_2, n_3, ...]$, this computes the581 Given the input `[n_1, n_2, n_3, ...]`, this computes the 582 582 multinomial coefficient $(n_1 + n_2 + n_3 + ...)! / (n_1! n_2! 583 n_3! ...) $, mod $p$. The method is this: expand each $n_i$in584 base $p$: $n_i = \sum_j p^j n_{ij}$. Do the same for the sum of585 the $n_i$'s, which we call $m$: $m = \sum_j p^j m_j$. Then the586 multinomial coefficient is congruent, mod $p$, to the product of587 the multinomial coefficients $m_j! / (n_{1j}! n_{2j}! ...)$.583 n_3! ...)`, mod `p`. The method is this: expand each `n_i` in 584 base `p`: `n_i = \sum_j p^j n_{ij}`. Do the same for the sum of 585 the `n_i`'s, which we call `m`: `m = \sum_j p^j m_j`. Then the 586 multinomial coefficient is congruent, mod `p`, to the product of 587 the multinomial coefficients `m_j! / (n_{1j}! n_{2j}! ...)`. 588 588 589 Furthermore, any multinomial coefficient $m! / (n_1! n_2! ...)$589 Furthermore, any multinomial coefficient `m! / (n_1! n_2! ...)` 590 590 can be computed as a product of binomial coefficients: it equals 591 591 592 592 .. MATH::
Note the pairs split over multiple lines.
comment:6 Changed 2 months ago by
 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
 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
 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
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 b class CoxeterGroups(Category_singleton): 2744 2744 OUTPUT: 2745 2745 2746 2746 The unique Bruhatmaximum element ``x`` in ``W`` such that ``x W' = w W'`` 2747 and ``v $\ge$``x``.2747 and ``v `\ge` ``x``.
Remove is
:

src/sage/categories/examples/semigroups_cython.pyx
a b class LeftZeroSemigroup(LeftZeroSemigroupPython): 151 151 sage: S.some_elements() 152 152 [3, 42, 'a', 3.4, 'raton laveur'] 153 153 154 with product rule is given by $a \times b = a$ for all $a,b$. ::154 with product rule is given by `a \times b = a` for all `a,b`. :: 155 155 156 156 sage: S('hello') * S('world')
Single \
:

src/sage/coding/guava.py
a b def QuasiQuadraticResidueCode(p): 62 62 sage: C = codes.QuasiQuadraticResidueCode(11); C # optional  gap_packages (Guava package) 63 63 [22, 11] linear code over GF(2) 64 64 65 These are selforthogonal in general and selfdual when $p \\equiv 3 \\pmod 4$.65 These are selforthogonal in general and selfdual when `p \\equiv 3 \\pmod 4`. 66 66 67 67 AUTHOR: David Joyner (112005)
\
before sin
:

src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py
a b class ParametrizedSurface3D(SageObject): 823 823 824 824 ALGORITHM: 825 825 826 The operator of rotation over $\pi/2$ is $J^i_j = g^{ik}\omega_{jk}$,827 where $\omega$is the area form. The operator of rotation over an828 angle $\theta$ is $\cos(\theta) I + sin(\theta) J$.826 The operator of rotation over `\pi/2` is `J^i_j = g^{ik}\omega_{jk}`, 827 where `\omega` is the area form. The operator of rotation over an 828 angle `\theta` is `\cos(\theta) I + sin(\theta) J`.
comment:10 Changed 2 months ago by
 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
Thanks a lot, done!
comment:12 followup: ↓ 14 Changed 2 months ago by
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
a b class NefPartition(SageObject, Hashable): 4263 4263 `\overline{N} = N \times \ZZ^k` are dual lattices. 4264 4264 4265 4265 The **Cayley polytope** `P \subset \overline{M}_\RR` of a nefpartition is 4266 given by $P = \mathrm{Conv}(\Delta_0 \times e_0, \Delta_1 \times e_1,4266 given by `P = \mathrm{Conv}(\Delta_0 \times e_0, \Delta_1 \times e_1, 4267 4267 \ldots, \Delta_{k1} \times e_{k1})`, where `\{e_i\}_{i=0}^{k1}` is the 4268 4268 standard basis of `\ZZ^k`. The **dual Cayley polytope** 4269 4269 `P^* \subset \overline{N}_\RR` is the Cayley polytope of the dual 
src/sage/groups/matrix_gps/isometries.py
diff git a/src/sage/groups/matrix_gps/isometries.py b/src/sage/groups/matrix_gps/isometries.py index ab611b4ce7..f9111a2c92 100644
a b 1 1 r""" 2 2 Groups of isometries. 3 3 4 Let `M = \ZZ^n` or `\QQ^n`, `b: M \times M \rightarrow \QQ $a bilinear form and5 $f: M \rightarrow M$ a linear map. We say that $f$is an isometry if for all6 elements $x,y$ of $M$ we have that $b(x,y)=b(f(x),f(y))$.7 A group of isometries is a subgroup of $GL(M)$consisting of isometries.4 Let `M = \ZZ^n` or `\QQ^n`, `b: M \times M \rightarrow \QQ` a bilinear form and 5 `f: M \rightarrow M` a linear map. We say that `f` is an isometry if for all 6 elements `x,y` of `M` we have that `b(x,y)=b(f(x),f(y))`. 7 A group of isometries is a subgroup of `GL(M)` consisting of isometries. 8 8 9 9 EXAMPLES:: 10 10 
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 b blowup in this single coordinate chart. Lets investigate further:: 231 231 So we see that the fiber over this point is an affine line. Together 232 232 with another affine line in the other coordinate patch, this covers 233 233 the exceptional `\mathbb{P}^1` of the blowup `O_{\mathbb{P}^1}(2) \to 234 \CC^2/\ZZ_2 $.234 \CC^2/\ZZ_2`. 235 235 236 236 Here is an example with higher dimensional varieties involved:: 237 237
After fixing these, if I make process_dollars(s)
just return s
, then the documentation builds successfully.
comment:13 Changed 2 months ago by
Thanks! Could you push these changes to the ticket please?
comment:14 in reply to: ↑ 12 Changed 2 months ago by
Replying to jhpalmieri:
After fixing these, if I make
process_dollars(s)
justreturn 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
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
 Description modified (diff)
comment:17 Changed 2 months ago by
 Branch changed from u/mkoeppe/replace_______in_docstrings_by______ to u/jhpalmieri/replace_______in_docstrings_by______
comment:18 Changed 2 months ago by
 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
 Reviewers set to Kwankyu Lee
 Status changed from needs_review to positive_review
LGTM in rendered documentation.
comment:20 Changed 2 months ago by
 Reviewers changed from Kwankyu Lee to Kwankyu Lee, Travis Scrimshaw
comment:21 Changed 2 months ago by
Thanks all!
comment:22 Changed 2 months ago by
 Branch changed from u/jhpalmieri/replace_______in_docstrings_by______ to afa5bed0f784d25343cbf9c95a680e5af1a3a61c
 Resolution set to fixed
 Status changed from positive_review to closed
New commits:
sage.algebras: Replace $...$ in docstrings by `...`
sage.calculus: Replace $...$ in docstrings by `...`
sage.categories, coding, databases: Replace $...$ in docstrings by `...`