More block tags, docstring cosmetics

Author: Matthias Koeppe

src/sage/data_structures/stream.py

@@ -2526,12 +2526,12 @@ def _approximate_order(self):
 
             sage: from sage.data_structures.stream import Stream_function, Stream_cauchy_invert
             sage: f = Stream_function(lambda n: GF(7)(n), True, 0)
-            sage: [f[i] for i in range(5)]                                              # needs sage.rings.finite_rings
+            sage: [f[i] for i in range(5)]
             [0, 1, 2, 3, 4]
-            sage: h = Stream_cauchy_invert(f)                                           # needs sage.rings.finite_rings
-            sage: h._approximate_order                                                  # needs sage.rings.finite_rings
+            sage: h = Stream_cauchy_invert(f)
+            sage: h._approximate_order
             -1
-            sage: [h[i] for i in range(-2, 5)]                                          # needs sage.rings.finite_rings
+            sage: [h[i] for i in range(-2, 5)]
             [0, 1, 5, 1, 0, 0, 0]
         """
         try:

src/sage/ext/fast_callable.pyx

@@ -2488,23 +2488,24 @@ cdef class Wrapper:
 
         EXAMPLES::
 
+            sage: # needs sage.symbolic
             sage: from sage.ext.fast_callable import ExpressionTreeBuilder, generate_code, InstructionStream
             sage: etb = ExpressionTreeBuilder('x')
             sage: x = etb.var('x')
-            sage: expr = (x+pi) * (x+1)                                                 # needs sage.symbolic
+            sage: expr = (x+pi) * (x+1)
             sage: from sage.ext.interpreters.wrapper_py import metadata, Wrapper_py
             sage: instr_stream = InstructionStream(metadata, 1)
-            sage: generate_code(expr, instr_stream)                                     # needs sage.symbolic
+            sage: generate_code(expr, instr_stream)
             sage: instr_stream.instr('return')
             sage: v = Wrapper_py(instr_stream.get_current())
-            sage: v.get_orig_args()                                                     # needs sage.symbolic
+            sage: v.get_orig_args()
             {'args': 1,
              'code': [0, 0, 1, 0, 4, 0, 0, 1, 1, 4, 6, 2],
              'constants': [pi, 1],
              'domain': None,
              'py_constants': [],
              'stack': 3}
-            sage: v.op_list()                                                           # needs sage.symbolic
+            sage: v.op_list()
             [('load_arg', 0), ('load_const', pi), 'add', ('load_arg', 0), ('load_const', 1), 'add', 'mul', 'return']
         """
 

src/sage/structure/coerce.pyx

@@ -423,15 +423,18 @@ cpdef bint is_numpy_type(t):
     EXAMPLES::
 
         sage: from sage.structure.coerce import is_numpy_type
-        sage: import numpy                                                              # needs numpy
-        sage: is_numpy_type(numpy.int16)                                                # needs numpy
+
+        sage: # needs numpy
+        sage: import numpy
+        sage: is_numpy_type(numpy.int16)
         True
-        sage: is_numpy_type(numpy.floating)                                             # needs numpy
+        sage: is_numpy_type(numpy.floating)
         True
-        sage: is_numpy_type(numpy.ndarray)                                              # needs numpy
+        sage: is_numpy_type(numpy.ndarray)
         True
-        sage: is_numpy_type(numpy.matrix)                                               # needs numpy
+        sage: is_numpy_type(numpy.matrix)
         True
+
         sage: is_numpy_type(int)
         False
         sage: is_numpy_type(Integer)
@@ -923,20 +926,23 @@ cdef class CoercionModel:
     cpdef analyse(self, xp, yp, op=mul):
         """
         Emulate the process of doing arithmetic between xp and yp, returning
-        a list of steps and the parent that the result will live in. The
-        ``explain`` function is easier to use, but if one wants access to
+        a list of steps and the parent that the result will live in.
+
+        The :meth:`explain` method is easier to use, but if one wants access to
         the actual morphism and action objects (rather than their string
-        representations) then this is the function to use.
+        representations), then this is the function to use.
 
         EXAMPLES::
 
             sage: cm = sage.structure.element.get_coercion_model()
             sage: GF7 = GF(7)
             sage: steps, res = cm.analyse(GF7, ZZ)
             sage: steps
-            ['Coercion on right operand via', Natural morphism:
+            ['Coercion on right operand via',
+             Natural morphism:
               From: Integer Ring
-              To:   Finite Field of size 7, 'Arithmetic performed after coercions.']
+              To:   Finite Field of size 7,
+             'Arithmetic performed after coercions.']
             sage: res
             Finite Field of size 7
             sage: f = steps[1]; type(f)
@@ -1016,9 +1022,10 @@ cdef class CoercionModel:
 
     def common_parent(self, *args):
         """
-        Computes a common parent for all the inputs. It's essentially
-        an `n`-ary canonical coercion except it can operate on parents
-        rather than just elements.
+        Compute a common parent for all the inputs.
+
+        It's essentially an `n`-ary canonical coercion except it can
+        operate on parents rather than just elements.
 
         INPUT:
 
@@ -1027,7 +1034,7 @@ cdef class CoercionModel:
         OUTPUT:
 
         A :class:`Parent` into which each input should coerce, or raises a
-        ``TypeError`` if no such :class:`Parent` can be found.
+        :class:`TypeError` if no such :class:`Parent` can be found.
 
         EXAMPLES::
 
@@ -1122,23 +1129,25 @@ cdef class CoercionModel:
 
     cpdef bin_op(self, x, y, op):
         """
-        Execute the operation op on x and y. It first looks for an action
-        corresponding to op, and failing that, it tries to coerces x and y
-        into a common parent and calls op on them.
+        Execute the operation ``op`` on `x` and `y`.
+
+        It first looks for an action
+        corresponding to ``op``, and failing that, it tries to coerce `x` and `y`
+        into a common parent and calls ``op`` on them.
 
-        If it cannot make sense of the operation, a TypeError is raised.
+        If it cannot make sense of the operation, a :class:`TypeError` is raised.
 
         INPUT:
 
-        - ``x``  - the left operand
+        - ``x`` -- the left operand
 
-        - ``y``  - the right operand
+        - ``y`` -- the right operand
 
-        - ``op`` - a python function taking 2 arguments
+        - ``op`` -- a python function taking 2 arguments
 
           .. NOTE::
 
-             op is often an arithmetic operation, but need not be so.
+             ``op`` is often an arithmetic operation, but need not be so.
 
         EXAMPLES::
 
@@ -1268,26 +1277,28 @@ cdef class CoercionModel:
 
     cpdef canonical_coercion(self, x, y):
         r"""
-        Given two elements x and y, with parents S and R respectively,
-        find a common parent Z such that there are coercions
-        `f: S \mapsto Z` and `g: R \mapsto Z` and return `f(x), g(y)`
+        Given two elements `x` and `y`, with parents `S` and `R` respectively,
+        find a common parent `Z` such that there are coercions
+        `f: S \to Z` and `g: R \to Z` and return `f(x), g(y)`,
         which will have the same parent.
 
-        Raises a type error if no such Z can be found.
+        Raises a type error if no such `Z` can be found.
 
         EXAMPLES::
 
             sage: cm = sage.structure.element.get_coercion_model()
             sage: cm.canonical_coercion(mod(2, 10), 17)
             (2, 7)
-            sage: x, y = cm.canonical_coercion(1/2, matrix(ZZ, 2, 2, range(4)))         # needs sage.modules
-            sage: x                                                                     # needs sage.modules
+
+            sage: # needs sage.modules
+            sage: x, y = cm.canonical_coercion(1/2, matrix(ZZ, 2, 2, range(4)))
+            sage: x
             [1/2   0]
             [  0 1/2]
-            sage: y                                                                     # needs sage.modules
+            sage: y
             [0 1]
             [2 3]
-            sage: parent(x) is parent(y)                                                # needs sage.modules
+            sage: parent(x) is parent(y)
             True
 
         There is some support for non-Sage datatypes as well::
@@ -1296,7 +1307,6 @@ cdef class CoercionModel:
             sage: type(x), type(y)
             (<class 'sage.rings.integer.Integer'>, <class 'sage.rings.integer.Integer'>)
 
-
             sage: x, y = cm.canonical_coercion(int(5), complex(3))
             sage: type(x), type(y)
             (<class 'complex'>, <class 'complex'>)
@@ -1411,7 +1421,6 @@ cdef class CoercionModel:
 
         raise TypeError("no common canonical parent for objects with parents: '%s' and '%s'"%(xp, yp))
 
-
     cpdef coercion_maps(self, R, S):
         r"""
         Give two parents `R` and `S`, return a pair of coercion maps
@@ -1471,12 +1480,14 @@ cdef class CoercionModel:
             False
             sage: cm = sage.structure.element.get_coercion_model()
             sage: cm.coercion_maps(V, W)
-            (None, (map internal to coercion system -- copy before use)
+            (None,
+             (map internal to coercion system -- copy before use)
              Coercion map:
                From: Vector space of dimension 3 over Rational Field
                To:   Vector space of dimension 3 over Rational Field)
             sage: cm.coercion_maps(W, V)
-            (None, (map internal to coercion system -- copy before use)
+            (None,
+             (map internal to coercion system -- copy before use)
              Coercion map:
                From: Vector space of dimension 3 over Rational Field
                To:   Vector space of dimension 3 over Rational Field)
@@ -1495,15 +1506,15 @@ cdef class CoercionModel:
             sage: # needs sage.libs.pari
             sage: import gc
             sage: T = type(GF(2))
-            sage: gc.collect() #random
+            sage: gc.collect()  # random
             852
             sage: N0 = len(list(o for o in gc.get_objects() if type(o) is T))
             sage: L = [ZZ(1) + GF(p)(1) for p in prime_range(2, 50)]
             sage: N1 = len(list(o for o in gc.get_objects() if type(o) is T))
             sage: N1 > N0
             True
             sage: del L
-            sage: gc.collect() #random
+            sage: gc.collect()  # random
             3939
             sage: N2 = len(list(o for o in gc.get_objects() if type(o) is T))
             sage: N2 - N0
@@ -1561,7 +1572,7 @@ cdef class CoercionModel:
 
     cpdef verify_coercion_maps(self, R, S, homs, bint fix=False):
         """
-        Make sure this is a valid pair of homomorphisms from R and S to a common parent.
+        Make sure this is a valid pair of homomorphisms from `R` and `S` to a common parent.
         This function is used to protect the user against buggy parents.
 
         EXAMPLES::
@@ -1631,7 +1642,7 @@ cdef class CoercionModel:
     cpdef discover_coercion(self, R, S):
         """
         This actually implements the finding of coercion maps as described in
-        the ``coercion_maps`` method.
+        the :meth:`coercion_maps` method.
 
         EXAMPLES::
 
@@ -1811,15 +1822,15 @@ cdef class CoercionModel:
         """
         INPUT:
 
-        - ``R`` - the left Parent (or type)
-        - ``S`` - the right Parent (or type)
-        - ``op`` - the operand, typically an element of the operator module
-        - ``r`` - (optional) element of R
-        - ``s`` - (optional) element of S.
+        - ``R`` -- the left :class:`Parent` (or type)
+        - ``S`` -- the right :class:`Parent` (or type)
+        - ``op`` -- the operand, typically an element of the :mod:`operator` module
+        - ``r`` -- (optional) element of `R`
+        - ``s`` -- (optional) element of `S`.
 
         OUTPUT:
 
-        - An action A such that s op r is given by A(s,r).
+        - An action `A` such that `s` ``op`` `r` is given by `A(s,r)`.
 
         The steps taken are illustrated below.
 
@@ -1833,13 +1844,14 @@ cdef class CoercionModel:
             True
             sage: cm = sage.structure.element.get_coercion_model()
 
-        If R or S is a Parent, ask it for an action by/on R::
+        If `R` or `S` is a :class:`Parent`, ask it for an action by/on `R`::
 
             sage: cm.discover_action(ZZ, P, operator.mul)
             Left scalar multiplication by Integer Ring on
              Univariate Polynomial Ring in x over Integer Ring
 
-        If R or S a type, recursively call get_action with the Sage versions of R and/or S::
+        If `R` or `S` a type, recursively call :meth:`get_action`
+        with the Sage versions of `R` and/or `S`::
 
             sage: cm.discover_action(P, int, operator.mul)
             Right scalar multiplication by Integer Ring on
@@ -1848,7 +1860,7 @@ cdef class CoercionModel:
               From: Set of Python objects of class 'int'
               To:   Integer Ring
 
-        If op is division, look for action on right by inverse::
+        If ``op`` is division, look for action on ``right`` by inverse::
 
             sage: cm.discover_action(P, ZZ, operator.truediv)
             Right inverse action by Rational Field on

src/sage/structure/coerce_actions.pyx

@@ -130,8 +130,7 @@ cdef class ActOnAction(GenericAction):
             y^2 + x - z
             sage: A(x + 2*y + 3*z, G((1,3,2)))
             2*x + 3*y + z
-
-            sage: type(A)                                                               # needs sage.groups
+            sage: type(A)
             <... 'sage.structure.coerce_actions.ActOnAction'>
         """
         return (<Element>g)._act_on_(x, self._is_left)
@@ -152,8 +151,7 @@ cdef class ActedUponAction(GenericAction):
             Infinity
             sage: A(matrix(ZZ, 2, [1,0,2,-1]), Cusp(1,2))
             Infinity
-
-            sage: type(A)                                                               # needs sage.modular sage.modules
+            sage: type(A)
             <... 'sage.structure.coerce_actions.ActedUponAction'>
         """
         return (<Element>x)._acted_upon_(g, not self._is_left)

src/sage/structure/element.pyx

@@ -3243,25 +3243,31 @@ cdef class CommutativeRingElement(RingElement):
 
     def sqrt(self, extend=True, all=False, name=None):
         """
-        It computes the square root.
+        Compute the square root.
 
         INPUT:
 
-        -  ``extend`` -- Whether to make a ring extension containing a square root if ``self`` is not a square (default: ``True``)
+        - ``extend`` -- boolean (default: ``True``); whether to make a ring
+           extension containing a square root if ``self`` is not a square
 
-        -  ``all`` -- Whether to return a list of all square roots or just a square root (default: False)
+        - ``all`` -- boolean (default: ``False``); whether to return a list of
+           all square roots or just a square root
 
-        -  ``name`` -- Required when ``extend=True`` and ``self`` is not a square. This will be the name of the generator extension.
+        - ``name`` -- required when ``extend=True`` and ``self`` is not a
+           square. This will be the name of the generator of the extension.
 
         OUTPUT:
 
-        - if ``all=False`` it returns a square root. (throws an error if ``extend=False`` and ``self`` is not a square)
+        - if ``all=False``, a square root; raises an error if ``extend=False``
+          and ``self`` is not a square
 
-        - if ``all=True`` it returns a list of all the square roots (could be empty if ``extend=False`` and ``self`` is not a square)
+        - if ``all=True``, a list of all the square roots (empty if
+          ``extend=False`` and ``self`` is not a square)
 
         ALGORITHM:
 
-        It uses ``is_square(root=true)`` for the hard part of the work, the rest is just wrapper code.
+        It uses ``is_square(root=true)`` for the hard part of the work, the rest
+        is just wrapper code.
 
         EXAMPLES::
 
@@ -3320,9 +3326,9 @@ cdef class CommutativeRingElement(RingElement):
             y
             sage: sqrtx^2
             1/x
-            sage: (1/x).sqrt(all=true,name="y")
+            sage: (1/x).sqrt(all=true, name="y")
             [y, -y]
-            sage: (1/x).sqrt(extend=False,all=True)
+            sage: (1/x).sqrt(extend=False, all=True)
             []
             sage: (1/(x^2-1)).sqrt()
             Traceback (most recent call last):