Trac #34163: Fix docstring markup in sage/interfaces

Part of #34157: {{{ sage/interfaces/qepcad.py:631:1: RST205 Explicit markup ends without a blank line; unexpected unindent. sage/interfaces/qepcad.py:635:1: RST218 Literal block expected; none found. sage/interfaces/polymake.py:456:1: RST201 Block quote ends without a blank line; unexpected unindent. sage/interfaces/jmoldata.py:35:1: RST303 Unknown directive type "todo". sage/interfaces/frobby.py:365:1: RST218 Literal block expected; none found. sage/interfaces/interface.py:257:1: RST301 Unexpected indentation. sage/interfaces/interface.py:258:1: RST201 Block quote ends without a blank line; unexpected unindent. sage/interfaces/interface.py:448:1: RST213 Inline emphasis start-string without end-string. sage/interfaces/mathics.py:983:1: RST301 Unexpected indentation. sage/interfaces/mathics.py:984:1: RST202 Bullet list ends without a blank line; unexpected unindent. sage/interfaces/mathics.py:987:1: RST301 Unexpected indentation. sage/interfaces/mathics.py:988:1: RST201 Block quote ends without a blank line; unexpected unindent. sage/interfaces/mathics.py:995:1: RST301 Unexpected indentation. sage/interfaces/r.py:301:1: RST218 Literal block expected; none found. sage/interfaces/r.py:340:1: RST301 Unexpected indentation. sage/interfaces/r.py:507:1: RST218 Literal block expected; none found. sage/interfaces/r.py:1393:1: RST202 Bullet list ends without a blank line; unexpected unindent. sage/interfaces/r.py:2076:1: RST201 Block quote ends without a blank line; unexpected unindent. sage/interfaces/r.py:2078:1: RST301 Unexpected indentation. sage/interfaces/ecm.py:358:1: RST201 Block quote ends without a blank line; unexpected unindent. sage/interfaces/ecm.py:388:1: RST301 Unexpected indentation. sage/interfaces/ecm.py:389:1: RST201 Block quote ends without a blank line; unexpected unindent. sage/interfaces/ecm.py:391:1: RST301 Unexpected indentation. sage/interfaces/mathematica.py:416:1: RST218 Literal block expected; none found. sage/interfaces/mathematica.py:729:1: RST301 Unexpected indentation. sage/interfaces/mathematica.py:730:1: RST202 Bullet list ends without a blank line; unexpected unindent. sage/interfaces/mathematica.py:733:1: RST301 Unexpected indentation. sage/interfaces/mathematica.py:734:1: RST201 Block quote ends without a blank line; unexpected unindent. sage/interfaces/mathematica.py:741:1: RST301 Unexpected indentation. sage/interfaces/mupad.py:168:1: RST201 Block quote ends without a blank line; unexpected unindent. sage/interfaces/giac.py:919:1: RST218 Literal block expected; none found. sage/interfaces/giac.py:1069:1: RST301 Unexpected indentation. sage/interfaces/giac.py:1070:1: RST202 Bullet list ends without a blank line; unexpected unindent. sage/interfaces/magma.py:2631:1: RST218 Literal block expected; none found. sage/interfaces/phc.py:505:1: RST201 Block quote ends without a blank line; unexpected unindent. }}} URL: https://trac.sagemath.org/34163 Reported by: klee Ticket author(s): Frédéric Chapoton Reviewer(s): Kwankyu Lee
sagemath · Jul 25, 2022 · b03229e · b03229e
2 parents 46849b8 + c79ff66
commit b03229e
Show file tree

Hide file tree

Showing 13 changed files with 74 additions and 74 deletions.
diff --git a/src/sage/interfaces/ecm.py b/src/sage/interfaces/ecm.py
@@ -336,8 +336,8 @@ def recommended_B1(self, factor_digits):
         r'(?P<primality>.*) cofactor (?P<cofactor>\d+) has [\s]*(?P<digits>\d+) digits')
 
     def _parse_output(self, n, out):
-        """
-        Parse the ECM output
+        r"""
+        Parse the ECM output.
 
         INPUT:
 
@@ -348,10 +348,9 @@ def _parse_output(self, n, out):
         OUTPUT:
 
         List of pairs ``(integer, bool)`` consisting of factors of the
-        ECM input and whether they are deemed to be probable
-        prime. Note that ECM is not a good primality test, and there
-        is a sizeable probability that the "probable prime" is
-        actually composite.
+        ECM input and whether they are deemed to be probable prime.
+        Note that ECM is not a good primality test, and there is a
+        sizeable probability that the "probable prime" is actually composite.
 
         EXAMPLES::
 

diff --git a/src/sage/interfaces/frobby.py b/src/sage/interfaces/frobby.py
@@ -361,7 +361,7 @@ def _parse_4ti2_matrix(self, string):
         A list of rows of the matrix, where each row is represented as
         a list of integers.
 
-        EXAMPLES::
+        EXAMPLES:
 
         The format is straight-forward, as this example shows. ::
 

diff --git a/src/sage/interfaces/giac.py b/src/sage/interfaces/giac.py
@@ -903,8 +903,6 @@ def _richcmp_(self, other, op):
             sage: a == 5
             True
 
-        ::
-
             sage: c = giac(3)
             sage: a == c
             False
@@ -915,8 +913,6 @@ def _richcmp_(self, other, op):
             sage: c <= a
             True
 
-        ::
-
         TESTS::
 
             sage: x = var('x')
@@ -1065,10 +1061,11 @@ def _sage_(self, locals=None):
 
             This method works successfully when Giac returns a result
             or list of results that consist only of:
+
             - numbers, i.e. integers, floats, complex numbers;
             - functions and named constants also present in Sage, where:
                 - Sage knows how to translate the function or constant's name
-                from Giac's naming scheme through the ``symbol_table``, or
+                  from Giac's naming scheme through the ``symbol_table``, or
                 - you provide a translation dictionary ``locals``.
 
         New conversions can be added using Pynac's ``register_symbol``.

diff --git a/src/sage/interfaces/interface.py b/src/sage/interfaces/interface.py
@@ -248,15 +248,16 @@ def execute(self, *args, **kwds):
         return self.eval(*args, **kwds)
 
     def __call__(self, x, name=None):
-
         r"""
-        Create a new object in self from x.
+        Create a new object in ``self`` from ``x``.
+
+        The object ``X`` returned can be used like any Sage object, and
+        wraps an object in ``self``.  The standard arithmetic operators
+        work.  Moreover if ``foo`` is a function then::
+
+            ``X.foo(y,z,...)``
 
-        The object X returned can be used like any Sage object, and
-        wraps an object in self.  The standard arithmetic operators
-        work.  Moreover if foo is a function then
-                      X.foo(y,z,...)
-        calls foo(X, y, z, ...) and returns the corresponding object.
+        calls ``foo(X, y, z, ...)`` and returns the corresponding object.
 
         EXAMPLES::
 
@@ -446,7 +447,7 @@ def _relation_symbols(self):
 
     def _exponent_symbol(self):
         """
-        Return the symbol used to denote *10^ in floats, e.g 'e' in 1.5e6
+        Return the symbol used to denote ``*10^`` in floats, e.g 'e' in 1.5e6
 
         EXAMPLES::
 

diff --git a/src/sage/interfaces/jmoldata.py b/src/sage/interfaces/jmoldata.py
@@ -31,12 +31,13 @@
 import sys
 from pathlib import Path
 
+
 class JmolData(SageObject):
     r"""
-    .. todo::
+    .. TODO::
 
-       Create an animated image file (GIF) if spin is on and put data
-       extracted from a file into a variable/string/structure to return
+        Create an animated image file (GIF) if spin is on and put data
+        extracted from a file into a variable/string/structure to return
     """
     def __init__(self):
         """

diff --git a/src/sage/interfaces/magma.py b/src/sage/interfaces/magma.py
@@ -2627,7 +2627,7 @@ def __bool__(self):
             sage: bool(magma(0))                          # optional - magma
             False
 
-        TESTS::
+        TESTS:
 
         Verify that :trac:`32602` is fixed::
 

diff --git a/src/sage/interfaces/mathematica.py b/src/sage/interfaces/mathematica.py
@@ -453,14 +453,14 @@ def _un_camel(name):
 
     EXAMPLES::
 
-    sage: sage.interfaces.mathematica._un_camel('CamelCase')
-    'camel_case'
-    sage: sage.interfaces.mathematica._un_camel('EllipticE')
-    'elliptic_e'
-    sage: sage.interfaces.mathematica._un_camel('FindRoot')
-    'find_root'
-    sage: sage.interfaces.mathematica._un_camel('GCD')
-    'gcd'
+        sage: sage.interfaces.mathematica._un_camel('CamelCase')
+        'camel_case'
+        sage: sage.interfaces.mathematica._un_camel('EllipticE')
+        'elliptic_e'
+        sage: sage.interfaces.mathematica._un_camel('FindRoot')
+        'find_root'
+        sage: sage.interfaces.mathematica._un_camel('GCD')
+        'gcd'
     """
     s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
     return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
@@ -764,17 +764,20 @@ def _sage_(self, locals={}):
 
         This method works successfully when Mathematica returns a result
         or list of results that consist only of:
+
         - numbers, i.e. integers, floats, complex numbers;
         - functions and named constants also present in Sage, where:
             - Sage knows how to translate the function or constant's name
-            from Mathematica's naming scheme, or
+              from Mathematica's naming scheme, or
             - you provide a translation dictionary `locals`, or
             - the Sage name for the function or constant is simply the
-             Mathematica name in lower case;
-        - symbolic variables whose names don't pathologically overlap with
+              Mathematica name in lower case;
+
+        - symbolic variables whose names do not pathologically overlap with
           objects already defined in Sage.
 
         This method will not work when Mathematica's output includes:
+
         - strings;
         - functions unknown to Sage that are not specified in `locals`;
         - Mathematica functions with different parameters/parameter order to

diff --git a/src/sage/interfaces/mathics.py b/src/sage/interfaces/mathics.py
@@ -979,17 +979,20 @@ def _sage_(self, locals={}):
 
         This method works successfully when Mathics returns a result
         or list of results that consist only of:
+
         - numbers, i.e. integers, floats, complex numbers;
         - functions and named constants also present in Sage, where:
             - Sage knows how to translate the function or constant's name
-            from Mathics's naming scheme, or
+              from Mathics's naming scheme, or
             - you provide a translation dictionary `locals`, or
             - the Sage name for the function or constant is simply the
-             Mathics name in lower case;
-        - symbolic variables whose names don't pathologically overlap with
+              Mathics name in lower case;
+
+        - symbolic variables whose names do not pathologically overlap with
           objects already defined in Sage.
 
         This method will not work when Mathics's output includes:
+
         - strings;
         - functions unknown to Sage;
         - Mathics functions with different parameters/parameter order to

diff --git a/src/sage/interfaces/mupad.py b/src/sage/interfaces/mupad.py
@@ -157,22 +157,20 @@ def __reduce__(self):
         return reduce_load_mupad, tuple([])
 
     def _read_in_file_command(self, filename):
-        """
+        r"""
         EXAMPLES::
 
             sage: mupad._read_in_file_command('test')
             'read("test")'
 
             sage: filename = tmp_filename()
-            sage: f = open(filename, 'w')
-            sage: _ = f.write('x := 2;\n')
-            sage: f.close()
+            sage: with open(filename, 'w') as f:
+            ....:     _ = f.write('x := 2;\n')
             sage: mupad.read(filename)   # optional - MuPAD
             sage: mupad.get('x').strip() # optional - mupad
             '2'
-
         """
-        return 'read("%s")'%filename
+        return 'read("%s")' % filename
 
     def _quit_string(self):
         """

diff --git a/src/sage/interfaces/phc.py b/src/sage/interfaces/phc.py
@@ -482,19 +482,17 @@ def _output_from_command_list(self, command_list, polys, verbose=False):
         return output_filename
 
     def _input_file(self, polys):
-        """
+        r"""
         This is used internally to implement the PHC interface.
 
         INPUT:
 
         - polys -- a list of polynomials in a Sage polynomial ring
-          over a field that embeds into the complex
-          numbers.
+          over a field that embeds into the complex numbers
 
         OUTPUT:
 
-        - a PHC input file (as a text string) that describes these -
-          polynomials.
+        a PHC input file (as a text string) that describes these polynomials
 
         EXAMPLES::
 

diff --git a/src/sage/interfaces/polymake.py b/src/sage/interfaces/polymake.py
@@ -449,7 +449,7 @@ def _equality_symbol(self):
         return "=="
 
     def _read_in_file_command(self, filename):
-        """
+        r"""
         TESTS::
 
             sage: polymake._read_in_file_command('foobar')
@@ -466,7 +466,6 @@ def _read_in_file_command(self, filename):
             sage: L = polymake([42] * 84)                       # optional - polymake
             sage: len(L)                                        # optional - polymake
             84
-
         """
         return 'eval read_file "{}";\n'.format(filename)
 

diff --git a/src/sage/interfaces/qepcad.py b/src/sage/interfaces/qepcad.py
@@ -628,14 +628,16 @@ def _qepcad_atoms(formula):
 
     - `formula` (string) - a quantifier-free formula.
 
-    .. note:: this function is pis-aller used for doctesting, not a complete
-    parser, which should be written in a further ticket.
+    .. NOTE::
+
+        This function is pis-aller used for doctesting, not a complete
+        parser, which should be written in a further ticket.
 
     EXAMPLES::
 
-    sage: from sage.interfaces.qepcad import _qepcad_atoms
-    sage: _qepcad_atoms('y^5 + 4 y + 8 >= 0 /\\ y <= 0 /\\ [ y = 0 \\/ y^5 + 4 y + 8 = 0 ]')
-    {'y <= 0', 'y = 0', 'y^5 + 4 y + 8 = 0', 'y^5 + 4 y + 8 >= 0'}
+        sage: from sage.interfaces.qepcad import _qepcad_atoms
+        sage: _qepcad_atoms('y^5 + 4 y + 8 >= 0 /\\ y <= 0 /\\ [ y = 0 \\/ y^5 + 4 y + 8 = 0 ]')
+        {'y <= 0', 'y = 0', 'y^5 + 4 y + 8 = 0', 'y^5 + 4 y + 8 >= 0'}
     """
     return set(i.strip() for i in flatten([i.split('\\/') for i in formula.replace('[','').replace(']','').split('/\\')]))
 

diff --git a/src/sage/interfaces/r.py b/src/sage/interfaces/r.py
@@ -297,13 +297,12 @@ def _setup_r_to_sage_converter():
     Set up a the converter used to convert from rpy2's
     representation of R objects to the one sage expects.
 
-    EXAMPLES::
-
-    Test
+    EXAMPLES:
 
-    Simple numeric values are represented as vectors in R. So `1` would actually
-    be an array of length 1. We convert all vectors of length 1 to simple values,
-    whether or not they "originally" were simple values or not:
+    Simple numeric values are represented as vectors in R. So `1`
+    would actually be an array of length 1. We convert all vectors of
+    length 1 to simple values, whether or not they "originally" were
+    simple values or not::
 
         sage: r([42]).sage()  # optional - rpy2
         42
@@ -314,27 +313,27 @@ def _setup_r_to_sage_converter():
         sage: r('c("foo")').sage()  # optional - rpy2
         'foo'
 
-    Arrays of length greater than one are treated normally:
+    Arrays of length greater than one are treated normally::
 
         sage: r([42, 43]).sage()  # optional - rpy2
         [42, 43]
 
     We also convert all numeric values to integers if that is possible without
-    loss of precision:
+    loss of precision::
 
         sage: type(r([1.0]).sage()) == int  # optional - rpy2
         True
 
         sage: r([1.0, 42.5]).sage()  # optional - rpy2
         [1, 42.5]
 
-    Matrices are converted to sage matrices:
+    Matrices are converted to sage matrices::
 
         sage: r('matrix(c(2,4,3,1,5,7), nrow=2, ncol=3)').sage()  # optional - rpy2
         [2 3 5]
         [4 1 7]
 
-    More complex r structures are represented by dictionaries:
+    More complex r structures are represented by dictionaries::
 
         sage: r.summary(1).sage()  # optional - rpy2
         {'DATA': [1, 1, 1, 1, 1, 1],
@@ -345,7 +344,7 @@ def _setup_r_to_sage_converter():
         {'DATA': {'width': 60}, '_Names': 'width'}
 
     The conversion can handle "not a number", infintiy, imaginary values and
-    missing values:
+    missing values::
 
         sage: r(-17).sqrt().sage()  # optional - rpy2
         nan
@@ -356,8 +355,7 @@ def _setup_r_to_sage_converter():
         sage: inf = r('Inf'); inf.sage()  # optional - rpy2
         inf
 
-
-    Character Vectors are represented by regular python arrays:
+    Character Vectors are represented by regular python arrays::
 
         sage: labs = r.paste('c("X","Y")', '1:10', sep='""'); labs.sage()  # optional - rpy2
         ['X1', 'Y2', 'X3', 'Y4', 'X5', 'Y6', 'X7', 'Y8', 'X9', 'Y10']
@@ -503,9 +501,9 @@ def _lazy_init(self):
         the blas implementation that is used.
         For details, see https://bitbucket.org/rpy2/rpy2/issues/491.
 
-        TESTS::
+        TESTS:
 
-        Initialization happens on eval:
+        Initialization happens on eval::
 
              sage: my_r = R()  # optional - rpy2
              sage: my_r._initialized  # optional - rpy2
@@ -1391,6 +1389,7 @@ def __getitem__(self, s):
         INPUT:
 
         - s -- a string
+
         OUTPUT: RFunction -- the R function that in R has name s
 
         EXAMPLES::
@@ -2061,13 +2060,14 @@ def r_version():
     """
     return r.version()
 
+
 class HelpExpression(str):
     """
     Used to improve printing of output of r.help.
     """
     def __repr__(self):
-        """
-        Return string representation of self.
+        r"""
+        Return string representation of ``self``.
 
         OUTPUT: string
 
@@ -2082,4 +2082,3 @@ def __repr__(self):
             R!
         """
         return str(self)
-
-Original file line number
+Diff line change
@@ Expand Up / @@ -2627,7 +2627,7 @@ def __bool__(self): @@
                 sage: bool(magma(0))                          # optional - magma
                 False
-            TESTS::
+            TESTS:
             Verify that :trac:`32602` is fixed::
@@ Expand Down @@