sage.rings: Reformat doctests, add # optional annotations

src/doc/en/reference/rings/index.rst

@@ -8,6 +8,7 @@ Base Classes for Rings, Algebras and Fields
    :maxdepth: 1
 
    sage/rings/ring
+   sage/rings/abc
 
 Ideals
 ------

src/sage/misc/cachefunc.pyx

@@ -850,6 +850,7 @@ cdef class CachedFunction():
             sage: I = P*[x,y]
             sage: from sage.misc.sageinspect import sage_getdoc
             sage: print(sage_getdoc(I.groebner_basis)) # indirect doctest
+            WARNING: the enclosing module is marked...
                Return the reduced Groebner basis of this ideal.
             ...
 

src/sage/misc/latex.py

@@ -647,6 +647,7 @@ def latex_extra_preamble():
         \newcommand{\RLF}{\Bold{R}}
         \newcommand{\SL}{\mathrm{SL}}
         \newcommand{\PSL}{\mathrm{PSL}}
+        \newcommand{\lcm}{\mathop{\operatorname{lcm}}}
         \newcommand{\Bold}[1]{\mathbf{#1}}
         <BLANKLINE>
     """

src/sage/misc/latex_macros.py

@@ -173,7 +173,8 @@ def convert_latex_macro_to_mathjax(macro):
 
 # Use this list to define additional latex macros for sage documentation
 latex_macros = [r"\newcommand{\SL}{\mathrm{SL}}",
-                r"\newcommand{\PSL}{\mathrm{PSL}}"]
+                r"\newcommand{\PSL}{\mathrm{PSL}}",
+                r"\newcommand{\lcm}{\mathop{\operatorname{lcm}}}"]
 
 # The following is to allow customization of typesetting of rings:
 # mathbf vs mathbb.  See latex.py for more information.

src/sage/misc/sageinspect.py

@@ -1920,8 +1920,8 @@ def _sage_getdoc_unformatted(obj):
         Integer(x=None, base=0)
         File: sage/rings/integer.pyx (starting at line ...)
         <BLANKLINE>
-            The ``Integer`` class represents arbitrary precision
-            integers. It derives from the ``Element`` class, so
+            The :class:`Integer` class represents arbitrary precision
+            integers. It derives from the :class:`Element` class, so
             integers can be used as ring elements anywhere in Sage.
         ...
 
@@ -1995,8 +1995,8 @@ def sage_getdoc_original(obj):
 
         sage: print(sage_getdoc_original(sage.rings.integer.Integer))
         <BLANKLINE>
-            The ``Integer`` class represents arbitrary precision
-            integers. It derives from the ``Element`` class, so
+            The :class:`Integer` class represents arbitrary precision
+            integers. It derives from the :class:`Element` class, so
             integers can be used as ring elements anywhere in Sage.
         ...
 

src/sage/rings/abc.pyx

@@ -14,13 +14,13 @@ class NumberField_quadratic(Field):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: K.<sqrt2> = QuadraticField(2)                                     # optional - sage.rings.number_field
-        sage: isinstance(K, sage.rings.abc.NumberField_quadratic)               # optional - sage.rings.number_field
+        sage: K.<sqrt2> = QuadraticField(2)                                             # optional - sage.rings.number_field
+        sage: isinstance(K, sage.rings.abc.NumberField_quadratic)                       # optional - sage.rings.number_field
         True
 
     By design, there is a unique direct subclass::
 
-        sage: sage.rings.abc.NumberField_quadratic.__subclasses__()             # optional - sage.rings.number_field
+        sage: sage.rings.abc.NumberField_quadratic.__subclasses__()                     # optional - sage.rings.number_field
         [<class 'sage.rings.number_field.number_field.NumberField_quadratic'>]
 
         sage: len(sage.rings.abc.NumberField_quadratic.__subclasses__()) <= 1
@@ -40,13 +40,13 @@ class NumberField_cyclotomic(Field):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: K.<zeta> = CyclotomicField(15)                                    # optional - sage.rings.number_field
-        sage: isinstance(K, sage.rings.abc.NumberField_cyclotomic)              # optional - sage.rings.number_field
+        sage: K.<zeta> = CyclotomicField(15)                                            # optional - sage.rings.number_field
+        sage: isinstance(K, sage.rings.abc.NumberField_cyclotomic)                      # optional - sage.rings.number_field
         True
 
     By design, there is a unique direct subclass::
 
-        sage: sage.rings.abc.NumberField_cyclotomic.__subclasses__()            # optional - sage.rings.number_field
+        sage: sage.rings.abc.NumberField_cyclotomic.__subclasses__()                    # optional - sage.rings.number_field
         [<class 'sage.rings.number_field.number_field.NumberField_cyclotomic'>]
 
         sage: len(sage.rings.abc.NumberField_cyclotomic.__subclasses__()) <= 1
@@ -66,16 +66,16 @@ class AlgebraicField_common(Field):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: isinstance(QQbar, sage.rings.abc.AlgebraicField_common)           # optional - sage.rings.number_field
+        sage: isinstance(QQbar, sage.rings.abc.AlgebraicField_common)                   # optional - sage.rings.number_field
         True
-        sage: isinstance(AA, sage.rings.abc.AlgebraicField_common)              # optional - sage.rings.number_field
+        sage: isinstance(AA, sage.rings.abc.AlgebraicField_common)                      # optional - sage.rings.number_field
         True
 
     By design, other than the abstract subclasses :class:`~sage.rings.abc.AlgebraicField`
     and :class:`~sage.rings.abc.AlgebraicRealField`, there is only one direct implementation
     subclass::
 
-        sage: sage.rings.abc.AlgebraicField_common.__subclasses__()             # optional - sage.rings.number_field
+        sage: sage.rings.abc.AlgebraicField_common.__subclasses__()                     # optional - sage.rings.number_field
         [<class 'sage.rings.abc.AlgebraicField'>,
          <class 'sage.rings.abc.AlgebraicRealField'>,
          <class 'sage.rings.qqbar.AlgebraicField_common'>]
@@ -97,14 +97,14 @@ class AlgebraicField(AlgebraicField_common):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: isinstance(QQbar, sage.rings.abc.AlgebraicField)                  # optional - sage.rings.number_field
+        sage: isinstance(QQbar, sage.rings.abc.AlgebraicField)                          # optional - sage.rings.number_field
         True
-        sage: isinstance(AA, sage.rings.abc.AlgebraicField)                     # optional - sage.rings.number_field
+        sage: isinstance(AA, sage.rings.abc.AlgebraicField)                             # optional - sage.rings.number_field
         False
 
     By design, there is a unique direct subclass::
 
-        sage: sage.rings.abc.AlgebraicField.__subclasses__()                    # optional - sage.rings.number_field
+        sage: sage.rings.abc.AlgebraicField.__subclasses__()                            # optional - sage.rings.number_field
         [<class 'sage.rings.qqbar.AlgebraicField'>]
 
         sage: len(sage.rings.abc.AlgebraicField.__subclasses__()) <= 1
@@ -124,14 +124,14 @@ class AlgebraicRealField(AlgebraicField_common):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: isinstance(QQbar, sage.rings.abc.AlgebraicRealField)              # optional - sage.rings.number_field
+        sage: isinstance(QQbar, sage.rings.abc.AlgebraicRealField)                      # optional - sage.rings.number_field
         False
-        sage: isinstance(AA, sage.rings.abc.AlgebraicRealField)                 # optional - sage.rings.number_field
+        sage: isinstance(AA, sage.rings.abc.AlgebraicRealField)                         # optional - sage.rings.number_field
         True
 
     By design, there is a unique direct subclass::
 
-        sage: sage.rings.abc.AlgebraicRealField.__subclasses__()                # optional - sage.rings.number_field
+        sage: sage.rings.abc.AlgebraicRealField.__subclasses__()                        # optional - sage.rings.number_field
         [<class 'sage.rings.qqbar.AlgebraicRealField'>]
 
         sage: len(sage.rings.abc.AlgebraicRealField.__subclasses__()) <= 1
@@ -376,13 +376,13 @@ class Order:
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: K.<a> = NumberField(x^2 + 1); O = K.order(2*a)                    # optional - sage.rings.number_field
-        sage: isinstance(O, sage.rings.abc.Order)                               # optional - sage.rings.number_field
+        sage: K.<a> = NumberField(x^2 + 1); O = K.order(2*a)                            # optional - sage.rings.number_field
+        sage: isinstance(O, sage.rings.abc.Order)                                       # optional - sage.rings.number_field
         True
 
     By design, there is a unique direct subclass::
 
-        sage: sage.rings.abc.Order.__subclasses__()                             # optional - sage.rings.number_field
+        sage: sage.rings.abc.Order.__subclasses__()                                     # optional - sage.rings.number_field
         [<class 'sage.rings.number_field.order.Order'>]
 
         sage: len(sage.rings.abc.Order.__subclasses__()) <= 1
@@ -402,14 +402,14 @@ class pAdicRing(EuclideanDomain):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: isinstance(Zp(5), sage.rings.abc.pAdicRing)
+        sage: isinstance(Zp(5), sage.rings.abc.pAdicRing)                               # optional - sage.rings.padics
         True
-        sage: isinstance(Qp(5), sage.rings.abc.pAdicRing)
+        sage: isinstance(Qp(5), sage.rings.abc.pAdicRing)                               # optional - sage.rings.padics
         False
 
     By design, there is a unique direct subclass::
 
-        sage: sage.rings.abc.pAdicRing.__subclasses__()
+        sage: sage.rings.abc.pAdicRing.__subclasses__()                                 # optional - sage.rings.padics
         [<class 'sage.rings.padics.generic_nodes.pAdicRingGeneric'>]
 
         sage: len(sage.rings.abc.pAdicRing.__subclasses__()) <= 1
@@ -429,14 +429,14 @@ class pAdicField(Field):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: isinstance(Zp(5), sage.rings.abc.pAdicField)
+        sage: isinstance(Zp(5), sage.rings.abc.pAdicField)                              # optional - sage.rings.padics
         False
-        sage: isinstance(Qp(5), sage.rings.abc.pAdicField)
+        sage: isinstance(Qp(5), sage.rings.abc.pAdicField)                              # optional - sage.rings.padics
         True
 
     By design, there is a unique direct subclass::
 
-        sage: sage.rings.abc.pAdicField.__subclasses__()
+        sage: sage.rings.abc.pAdicField.__subclasses__()                                # optional - sage.rings.padics
         [<class 'sage.rings.padics.generic_nodes.pAdicFieldGeneric'>]
 
         sage: len(sage.rings.abc.pAdicField.__subclasses__()) <= 1
@@ -456,13 +456,13 @@ cdef class SymbolicRing(CommutativeRing):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: isinstance(SR, sage.rings.abc.SymbolicRing)                       # optional - sage.symbolic
+        sage: isinstance(SR, sage.rings.abc.SymbolicRing)                               # optional - sage.symbolic
         True
 
     By design, other than the abstract subclass :class:`~sage.rings.abc.CallableSymbolicExpressionRing`,
     there is only one direct implementation subclass::
 
-        sage: sage.rings.abc.SymbolicRing.__subclasses__()                      # optional - sage.symbolic
+        sage: sage.rings.abc.SymbolicRing.__subclasses__()                              # optional - sage.symbolic
         [<class 'sage.rings.abc.CallableSymbolicExpressionRing'>,
          <class 'sage.symbolic.ring.SymbolicRing'>]
 
@@ -483,13 +483,13 @@ class CallableSymbolicExpressionRing(SymbolicRing):
     EXAMPLES::
 
         sage: import sage.rings.abc
-        sage: f = x.function(x).parent()                                        # optional - sage.symbolic
-        sage: isinstance(f, sage.rings.abc.CallableSymbolicExpressionRing)      # optional - sage.symbolic
+        sage: f = x.function(x).parent()                                                # optional - sage.symbolic
+        sage: isinstance(f, sage.rings.abc.CallableSymbolicExpressionRing)              # optional - sage.symbolic
         True
 
     By design, there is a unique direct subclass::
 
-        sage: sage.rings.abc.CallableSymbolicExpressionRing.__subclasses__()    # optional - sage.symbolic
+        sage: sage.rings.abc.CallableSymbolicExpressionRing.__subclasses__()            # optional - sage.symbolic
         [<class 'sage.symbolic.callable.CallableSymbolicExpressionRing_class'>]
 
         sage: len(sage.rings.abc.CallableSymbolicExpressionRing.__subclasses__()) <= 1

src/sage/rings/algebraic_closure_finite_field.py

@@ -1,3 +1,4 @@
+# sage.doctest: optional - sage.rings.finite_rings
 r"""
 Algebraic closures of finite fields
 

src/sage/rings/bernmm.pyx

@@ -13,7 +13,7 @@ Cython wrapper for bernmm library
 
 AUTHOR:
 
-    - David Harvey (2008-06): initial version
+- David Harvey (2008-06): initial version
 """
 
 #*****************************************************************************
@@ -42,18 +42,18 @@ from sage.rings.rational cimport Rational
 
 def bernmm_bern_rat(long k, int num_threads = 1):
     r"""
-    Computes k-th Bernoulli number using a multimodular algorithm.
+    Compute `k`-th Bernoulli number using a multimodular algorithm.
     (Wrapper for bernmm library.)
 
     INPUT:
 
-    - k -- non-negative integer
-    - num_threads -- integer >= 1, number of threads to use
+    - ``k`` -- non-negative integer
+    - ``num_threads`` -- integer `\geq 1`, number of threads to use
 
     COMPLEXITY:
 
-        Pretty much quadratic in `k`. See the paper "A multimodular algorithm
-        for computing Bernoulli numbers", David Harvey, 2008, for more details.
+    Pretty much quadratic in `k`. See the paper "A multimodular algorithm
+    for computing Bernoulli numbers", David Harvey, 2008, for more details.
 
     EXAMPLES::
 
@@ -98,18 +98,18 @@ def bernmm_bern_rat(long k, int num_threads = 1):
 
 def bernmm_bern_modp(long p, long k):
     r"""
-    Computes `B_k \mod p`, where `B_k` is the k-th Bernoulli number.
+    Compute `B_k \mod p`, where `B_k` is the `k`-th Bernoulli number.
 
-    If `B_k` is not `p`-integral, returns -1.
+    If `B_k` is not `p`-integral, return `-1`.
 
     INPUT:
 
-        p -- a prime
-        k -- non-negative integer
+    - ``p`` -- a prime
+    - ``k`` -- non-negative integer
 
     COMPLEXITY:
 
-        Pretty much linear in `p`.
+    Pretty much linear in `p`.
 
     EXAMPLES::
 

src/sage/rings/bernoulli_mod_p.pyx

@@ -53,11 +53,9 @@ def verify_bernoulli_mod_p(data):
 
     INPUT:
 
-        data -- list, same format as output of bernoulli_mod_p function
+    - ``data`` -- list, same format as output of :func:`bernoulli_mod_p` function
 
-    OUTPUT:
-
-        bool -- True if checksum passed
+    OUTPUT: bool -- True if checksum passed
 
     EXAMPLES::
 
@@ -102,7 +100,7 @@ def bernoulli_mod_p(int p):
 
     INPUT:
 
-    p -- integer, a prime
+    - ``p`` -- integer, a prime
 
     OUTPUT:
 
@@ -134,7 +132,7 @@ def bernoulli_mod_p(int p):
 
     AUTHOR:
 
-    -- David Harvey (2006-08-06)
+    - David Harvey (2006-08-06)
 
     """
 
@@ -233,12 +231,12 @@ def bernoulli_mod_p_single(long p, long k):
     r"""
     Return the Bernoulli number `B_k` mod `p`.
 
-    If `B_k` is not `p`-integral, an ArithmeticError is raised.
+    If `B_k` is not `p`-integral, an :class:`ArithmeticError` is raised.
 
     INPUT:
 
-    - p -- integer, a prime
-    - k -- non-negative integer
+    - ``p`` -- integer, a prime
+    - ``k`` -- non-negative integer
 
     OUTPUT:
 
@@ -274,7 +272,7 @@ def bernoulli_mod_p_single(long p, long k):
         ...
         ValueError: k must be non-negative
 
-    Check results against bernoulli_mod_p::
+    Check results against :class:`bernoulli_mod_p`::
 
         sage: bernoulli_mod_p(37)
          [1, 31, 16, 15, 16, 4, 17, 32, 22, 31, 15, 15, 17, 12, 29, 2, 0, 2]
@@ -303,8 +301,8 @@ def bernoulli_mod_p_single(long p, long k):
 
     AUTHOR:
 
-    -- David Harvey (2007-08-31)
-    -- David Harvey (2008-06): rewrote to use bernmm library
+    - David Harvey (2007-08-31)
+    - David Harvey (2008-06): rewrote to use bernmm library
 
     """
     if p <= 2:

src/sage/rings/cfinite_sequence.py

@@ -1038,7 +1038,7 @@ def an_element(self):
 
     def __contains__(self, x):
         """
-        Return True if x is an element of ``CFiniteSequences`` or
+        Return ``True`` if x is an element of ``CFiniteSequences`` or
         canonically coerces to this ring.
 
         EXAMPLES::