Trac #33973: Deprecate handling of $...$ in docstrings

We change the function `sage.misc.sagedoc.process_dollars` so it issues
a deprecation warning when dollar signs are used for math markup.

This is to provide a gentle transition for user packages that use  the
Sage docbuilding machinery.

URL: https://trac.sagemath.org/33973
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe, John Palmieri
Reviewer(s): Kwankyu Lee, John Palmieri

Author: Release Manager

src/doc/en/developer/coding_basics.rst

@@ -728,10 +728,9 @@ there is not one already. That is, you can do the following:
 LaTeX Typesetting
 -----------------
 
-In Sage's documentation LaTeX code is allowed and is marked with **backticks or
-dollar signs**:
+In Sage's documentation LaTeX code is allowed and is marked with **backticks**:
 
-    ```x^2 + y^2 = 1``` and ``$x^2 + y^2 = 1$`` both yield `x^2 + y^2 = 1`.
+    ```x^2 + y^2 = 1``` yields `x^2 + y^2 = 1`.
 
 **Backslashes:** For LaTeX commands containing backslashes, either use double
 backslashes or begin the docstring with a ``r"""`` instead of ``"""``. Both of
@@ -744,7 +743,7 @@ the following are valid::
 
     def sin(x):
         r"""
-        Return $\sin(x)$.
+        Return `\sin(x)`.
         """
 
 **MATH block:** This is similar to the LaTeX syntax ``\[<math expression>\]``

src/sage/combinat/words/suffix_trees.py

@@ -1570,7 +1570,7 @@ class DecoratedSuffixTree(ImplicitSuffixTree):
     A *decorated suffix tree* of a word `w` is the suffix tree of `w`
     marked with the end point of all squares in the `w`.
 
-    The symbol ``"$"`` is appended to ``w`` to ensure that each final
+    The symbol ``$`` is appended to ``w`` to ensure that each final
     state is a leaf of the suffix tree.
 
     INPUT:

src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py

@@ -1452,9 +1452,9 @@ def connection_coefficients(self):
         Computes the connection coefficients or Christoffel symbols
         `\Gamma^k_{ij}` of the surface. If the coefficients of the first
         fundamental form are given by `g_{ij}` (where `i, j = 1, 2`), then
-        $\Gamma^k_{ij} = \frac{1}{2} g^{kl} \left( \frac{\partial g_{li}}{\partial x^j}
+        `\Gamma^k_{ij} = \frac{1}{2} g^{kl} \left( \frac{\partial g_{li}}{\partial x^j}
         - \frac{\partial g_{ij}}{\partial x^l}
-        + \frac{\partial g_{lj}}{\partial x^i} \right)$.
+        + \frac{\partial g_{lj}}{\partial x^i} \right)`.
         Here, `(g^{kl})` is the inverse of the matrix `(g_{ij})`, with
         `i, j = 1, 2`.
 

src/sage/geometry/toric_plotter.py

@@ -836,7 +836,7 @@ def label_list(label, n, math_mode, index_set=None):
 
     If ``label`` was a list of ``n`` entries, it is returned without changes.
     If ``label`` is ``None``, a list of ``n`` ``None``'s is returned. If
-    ``label`` is a string, a list of strings of the form "$label_{i}$" is
+    ``label`` is a string, a list of strings of the form ``$label_{i}$`` is
     returned, where `i` ranges over ``index_set``. (If ``math_mode=False``, the
     form "label_i" is used instead.) If ``n=1``, there is no subscript added,
     unless ``index_set`` was specified explicitly.

src/sage/graphs/generators/classical_geometries.py

@@ -1433,7 +1433,7 @@ def Nowhere0WordsTwoWeightCodeGraph(q, hyperoval=None, field=None, check_hyperov
 
 def OrthogonalDualPolarGraph(e, d, q):
     r"""
-    Return the dual polar graph on $GO^e(n,q)$ of diameter `d`.
+    Return the dual polar graph on `GO^e(n,q)` of diameter `d`.
 
     The value of `n` is determined by `d` and `e`.
 

src/sage/groups/abelian_gps/dual_abelian_group_element.py

@@ -200,7 +200,7 @@ def word_problem(self, words, display=True):
             [[b^2*c^2*d^3*e^5, 245]]
 
         The command e.word_problem([u,v,w,x,y],display=True) returns
-        the same list but also prints $e = (b^2*c^2*d^3*e^5)^245$.
+        the same list but also prints ``e = (b^2*c^2*d^3*e^5)^245``.
         """
         ## First convert the problem to one using AbelianGroups
         import copy

src/sage/groups/braid.py

@@ -628,8 +628,8 @@ def LKB_matrix(self, variables='x,y'):
         r"""
         Return the Lawrence-Krammer-Bigelow representation matrix.
 
-        The matrix is expressed in the basis $\{e_{i, j} \mid 1\leq i
-        < j \leq n\}$, where the indices are ordered
+        The matrix is expressed in the basis `\{e_{i, j} \mid 1\leq i
+        < j \leq n\}`, where the indices are ordered
         lexicographically.  It is a matrix whose entries are in the
         ring of Laurent polynomials on the given variables.  By
         default, the variables are ``'x'`` and ``'y'``.
@@ -1345,7 +1345,7 @@ def _left_normal_form_coxeter(self):
 
         OUTPUT:
 
-        A tuple whose first element is the power of $\Delta$, and the
+        A tuple whose first element is the power of `\Delta`, and the
         rest are the permutations corresponding to the simple factors.
 
         EXAMPLES::
@@ -3081,8 +3081,8 @@ class group of the punctured disk.
         x_{j} & \text{otherwise}
         \end{cases},
 
-    where $\sigma_i$ are the generators of the braid group on $n$
-    strands, and $x_j$ the generators of the free group of rank $n$.
+    where `\sigma_i` are the generators of the braid group on `n`
+    strands, and `x_j` the generators of the free group of rank `n`.
 
     You should left multiplication of the free group element by the
     braid to compute the action. Alternatively, use the

src/sage/groups/perm_gps/permgroup_named.py

@@ -3,34 +3,34 @@
 
 You can construct the following permutation groups:
 
--- SymmetricGroup, $S_n$ of order $n!$ (n can also be a list $X$ of distinct
-                   positive integers, in which case it returns $S_X$)
+-- SymmetricGroup, `S_n` of order `n!` (n can also be a list `X` of distinct
+                   positive integers, in which case it returns `S_X`)
 
--- AlternatingGroup, $A_n$ of order $n!/2$ (n can also be a list $X$
+-- AlternatingGroup, `A_n` of order `n!/2` (n can also be a list `X`
                    of distinct positive integers, in which case it returns
-                   $A_X$)
+                   `A_X`)
 
--- DihedralGroup, $D_n$ of order $2n$
+-- DihedralGroup, `D_n` of order `2n`
 
--- GeneralDihedralGroup, $Dih(G)$, where G is an abelian group
+-- GeneralDihedralGroup, `Dih(G)`, where G is an abelian group
 
--- CyclicPermutationGroup, $C_n$ of order $n$
+-- CyclicPermutationGroup, `C_n` of order `n`
 
 -- DiCyclicGroup, nonabelian groups of order `4m` with a unique element of order 2
 
--- TransitiveGroup, $n^{th}$ transitive group of degree $d$
+-- TransitiveGroup, `n^{th}` transitive group of degree `d`
                       from the GAP tables of transitive groups
 
 -- TransitiveGroups(d), TransitiveGroups(), set of all of the above
 
--- PrimitiveGroup, $n^{th}$ primitive group of degree $d$
+-- PrimitiveGroup, `n^{th}` primitive group of degree `d`
                       from the GAP tables of primitive groups
 
 -- PrimitiveGroups(d), PrimitiveGroups(), set of all of the above
 
 -- MathieuGroup(degree), Mathieu group of degree 9, 10, 11, 12, 21, 22, 23, or 24.
 
--- KleinFourGroup, subgroup of $S_4$ of order $4$ which is not $C_2 \times C_2$
+-- KleinFourGroup, subgroup of `S_4` of order `4` which is not `C_2 \times C_2`
 
 -- QuaternionGroup, non-abelian group of order `8`, `\{\pm 1, \pm I, \pm J, \pm K\}`
 
@@ -39,24 +39,24 @@
 
 -- SemidihedralGroup, nonabelian 2-groups with cyclic subgroups of index 2
 
--- PGL(n,q), projective general linear group of $n\times n$ matrices over
+-- PGL(n,q), projective general linear group of `n\times n` matrices over
              the finite field GF(q)
 
--- PSL(n,q), projective special linear group of $n\times n$ matrices over
+-- PSL(n,q), projective special linear group of `n\times n` matrices over
              the finite field GF(q)
 
--- PSp(2n,q), projective symplectic linear group of $2n\times 2n$ matrices
+-- PSp(2n,q), projective symplectic linear group of `2n\times 2n` matrices
               over the finite field GF(q)
 
--- PSU(n,q), projective special unitary group of $n \times n$ matrices having
-             coefficients in the finite field $GF(q^2)$ that respect a
+-- PSU(n,q), projective special unitary group of `n \times n` matrices having
+             coefficients in the finite field `GF(q^2)` that respect a
              fixed nondegenerate sesquilinear form, of determinant 1.
 
--- PGU(n,q), projective general unitary group of $n\times n$ matrices having
-             coefficients in the finite field $GF(q^2)$ that respect a
+-- PGU(n,q), projective general unitary group of `n\times n` matrices having
+             coefficients in the finite field `GF(q^2)` that respect a
              fixed nondegenerate sesquilinear form, modulo the centre.
 
--- SuzukiGroup(q), Suzuki group over GF(q), $^2 B_2(2^{2k+1}) = Sz(2^{2k+1})$.
+-- SuzukiGroup(q), Suzuki group over GF(q), `^2 B_2(2^{2k+1}) = Sz(2^{2k+1})`.
 
 -- ComplexReflectionGroup, the complex reflection group `G(m, p, n)` or
                            the exceptional complex reflection group `G_m`
@@ -622,7 +622,7 @@ def algebra(self, base_ring, category=None):
 class AlternatingGroup(PermutationGroup_symalt):
     def __init__(self, domain=None):
         """
-        The alternating group of order $n!/2$, as a permutation group.
+        The alternating group of order `n!/2`, as a permutation group.
 
         INPUT:
 
@@ -968,8 +968,8 @@ def is_abelian(self):
 class KleinFourGroup(PermutationGroup_unique):
     def __init__(self):
         r"""
-        The Klein 4 Group, which has order $4$ and exponent $2$, viewed
-        as a subgroup of $S_4$.
+        The Klein 4 Group, which has order `4` and exponent `2`, viewed
+        as a subgroup of `S_4`.
 
         OUTPUT:
 
@@ -1703,7 +1703,7 @@ def _repr_(self):
 class MathieuGroup(PermutationGroup_unique):
     def __init__(self, n):
         """
-        The Mathieu group of degree $n$.
+        The Mathieu group of degree `n`.
 
         INPUT:
 
@@ -2777,7 +2777,7 @@ def ramification_module_decomposition_modular_curve(self):
 
         REFERENCE: D. Joyner and A. Ksir, 'Modular representations
                    on some Riemann-Roch spaces of modular curves
-                   $X(N)$', Computational Aspects of Algebraic Curves,
+                   `X(N)`', Computational Aspects of Algebraic Curves,
                    (Editor: T. Shaska) Lecture Notes in Computing, WorldScientific,
                    2005.)
 
@@ -2990,7 +2990,7 @@ class SuzukiGroup(PermutationGroup_unique):
     def __init__(self, q, name='a'):
         r"""
         The Suzuki group over GF(q),
-        $^2 B_2(2^{2k+1}) = Sz(2^{2k+1})$.
+        `^2 B_2(2^{2k+1}) = Sz(2^{2k+1})`.
 
         A wrapper for the GAP function SuzukiGroup.
 

src/sage/interfaces/frobby.py

@@ -144,8 +144,8 @@ def hilbert(self, monomial_ideal):
 
         The Hilbert-Poincaré series of a monomial ideal is the sum of all
         monomials not in the ideal. This sum can be written as a (finite)
-        rational function with $(x_1-1)(x_2-1)...(x_n-1)$ in the denominator,
-        assuming the variables of the ring are $x_1,x2,...,x_n$. This action
+        rational function with `(x_1-1)(x_2-1)...(x_n-1)` in the denominator,
+        assuming the variables of the ring are `x_1,x2,...,x_n`. This action
         computes the polynomial in the numerator of this fraction.
 
         INPUT: