Opened 2 months ago

Closed 2 months ago

#33968 closed enhancement (fixed)

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

Reported by: mkoeppe Owned by:
Priority: major Milestone: sage-9.7
Component: documentation Keywords:
Cc: tscrim, klee, jhpalmieri, gh-tobiasdiez 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:

Status badges

Description (last modified 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.

Change History (22)

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:

4c0e7d7sage.algebras: Replace $...$ in docstrings by `...`
7b6016fsage.calculus: Replace $...$ in docstrings by `...`
6e2d614sage.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:

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

03895c0sage.topology: Replace $...$ in docstrings by `...`
9715f3fsage.symbolic: Replace $...$ in docstrings by `...`
73ce3e3sage.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 b def multinomial(list): 
    327327
    328328    None if the multinomial coefficient is 0, or sum of list if it is 1
    329329
    330     Given the input $[n_1, n_2, n_3, ...]$, this computes the
     330    Given the input `[n_1, n_2, n_3, ...]`, this computes the
    331331    multinomial coefficient $(n_1 + n_2 + n_3 + ...)! / (n_1! n_2!
    332332    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, it
     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, it
    335335    is 1.
    336336
    337337    EXAMPLES::
    def milnor_multiplication_odd(m1,m2,p): 
    387387    a pair of tuples, as for r and s, and 'coeff' is an integer mod p.
    388388
    389389    This computes the product of the Milnor basis elements
    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, ...)$.
     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, ...)`.
    392392
    393393    EXAMPLES::
    394394
    def multinomial_odd(list,p): 
    578578
    579579    Associated multinomial coefficient, mod p
    580580
    581     Given the input $[n_1, n_2, n_3, ...]$, this computes the
     581    Given the input `[n_1, n_2, n_3, ...]`, this computes the
    582582    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$ 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}! ...)$.
     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}! ...)`.
    588588
    589     Furthermore, any multinomial coefficient $m! / (n_1! n_2! ...)$
     589    Furthermore, any multinomial coefficient `m! / (n_1! n_2! ...)`
    590590    can be computed as a product of binomial coefficients: it equals
    591591
    592592    .. 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:

cdb74b4src/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:

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

b215c7esage.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 b class CoxeterGroups(Category_singleton): 
    27442744            OUTPUT:
    27452745
    27462746            The unique Bruhat-maximum 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): 
    151151        sage: S.some_elements()
    152152        [3, 42, 'a', 3.4, 'raton laveur']
    153153
    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`. ::
    155155
    156156        sage: S('hello') * S('world')

Single \:

  • src/sage/coding/guava.py

    a b def QuasiQuadraticResidueCode(p): 
    6262        sage: C = codes.QuasiQuadraticResidueCode(11); C   # optional - gap_packages (Guava package)
    6363        [22, 11] linear code over GF(2)
    6464
    65     These are self-orthogonal in general and self-dual when $p \\equiv 3 \\pmod 4$.
     65    These are self-orthogonal in general and self-dual when `p \\equiv 3 \\pmod 4`.
    6666
    6767    AUTHOR: David Joyner (11-2005)

\ before sin:

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

    a b class ParametrizedSurface3D(SageObject): 
    823823
    824824        ALGORITHM:
    825825
    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$.
     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 git

  • Commit changed from b215c7e23bce4166d936c9dc8aec04959fde3e00 to 8e34f345233af19473f8b52afde5a398b5f08efc

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

8e34f34Reviewer fixes to docstrings

comment:11 Changed 2 months ago by mkoeppe

Thanks a lot, done!

comment:12 follow-up: 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
    a b class NefPartition(SageObject, Hashable): 
    42634263    `\overline{N} = N \times \ZZ^k` are dual lattices.
    42644264
    42654265    The **Cayley polytope** `P \subset \overline{M}_\RR` of a nef-partition 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,
    42674267    \ldots, \Delta_{k-1} \times e_{k-1})`, where `\{e_i\}_{i=0}^{k-1}` is the
    42684268    standard basis of `\ZZ^k`. The **dual Cayley polytope**
    42694269    `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  
    11r"""
    22Groups of isometries.
    33
    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.
     4Let `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
     6elements `x,y` of `M` we have that `b(x,y)=b(f(x),f(y))`.
     7A group of isometries is a subgroup of `GL(M)` consisting of isometries.
    88
    99EXAMPLES::
    1010
  • 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 blow-up in this single coordinate chart. Lets investigate further:: 
    231231So we see that the fiber over this point is an affine line. Together
    232232with another affine line in the other coordinate patch, this covers
    233233the exceptional `\mathbb{P}^1` of the blowup `O_{\mathbb{P}^1}(2) \to
    234 \CC^2/\ZZ_2$.
     234\CC^2/\ZZ_2`.
    235235
    236236Here is an example with higher dimensional varieties involved::
    237237

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

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?

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:

afa5bedtrac 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

comment:21 Changed 2 months ago by mkoeppe

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.