Another round of documentation clean-up.

cython/core/manifold.pyx

@@ -536,25 +536,22 @@ cdef class Manifold(Triangulation):
 
     def cover(self, permutation_rep):
         """
-        M.cover(permutation_rep)
-
-        Returns a Manifold representing the finite cover
-        specified by a transitive permutation representation.  The
-        representation is specified by a list of permutations, one for
-        each generator of the simplified presentation of the
-        fundamental group.  Each permutation is specified as a list P
-        such that set(P) == set(range(d)) where d is the degree of the
-        cover.
+        Returns a Manifold representing the finite cover specified by a
+        transitive permutation representation.  The representation is
+        specified by a list of permutations, one for each generator of the
+        simplified presentation of the fundamental group.  Each permutation is
+        specified as a list ``P`` such such that ``set(P) == set(range(d))``
+        where ``d`` is the degree of the cover.
 
         >>> M = Manifold('m004')
         >>> N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]])
         >>> abs(N0.volume()/M.volume() - 5) < 0.0000000001
         True
 
 
-        If within Sage, the permutations can also be of type
-        PermutationGroupElement, in which case they act on the set
-        range(1, d + 1).  Or, you can specify a GAP or Magma subgroup
+        If within SageMath, the permutations can also be of type
+        ``PermutationGroupElement``, in which case they act on the set
+        ``range(1, d + 1)``.  Or, you can specify a GAP or Magma subgroup
         of the fundamental group.     Some examples::
 
           sage: M = Manifold('m004')

cython/core/triangulation.pyx

@@ -347,8 +347,8 @@ cdef class Triangulation():
         If the manifold is stored as a link complement in your
         current session then it returns the number of components
         and crossing of the link. To view and interact with the
-        link see :py:meth:`spherogram.Link.view`
-        and :py:meth:`Manifold.plink`.
+        link see :meth:`spherogram.Link.view`
+        and :meth:`plink <snappy.Triangulation.plink>`.
         """
         if self._PDcode is not None:
             return spherogram.Link(self._PDcode)
@@ -360,7 +360,7 @@ cdef class Triangulation():
     cdef set_c_triangulation(self, c_Triangulation* c_triangulation):
         self.c_triangulation = c_triangulation
 
-    def num_cusps(self, cusp_type='all'):
+    def num_cusps(self, cusp_type='all') -> int:
         """
         Return the total number of cusps.  By giving the optional argument
         'orientable' or 'nonorientable' it will only count cusps of that type.
@@ -1046,7 +1046,7 @@ cdef class Triangulation():
                     repr += '(%g,%g)'% info['filling']
             return repr
 
-    def name(self):
+    def name(self) -> str:
         """
         Return the name of the triangulation.
 
@@ -1058,7 +1058,7 @@ cdef class Triangulation():
             return
         return to_str(get_triangulation_name(self.c_triangulation))
 
-    def set_name(self, new_name):
+    def set_name(self, new_name : str) -> None:
         """
         Give the triangulation a new name.
 
@@ -1113,7 +1113,7 @@ cdef class Triangulation():
     def _set_PDcode(self, code):
         self._PDcode = code
 
-    def num_tetrahedra(self):
+    def num_tetrahedra(self) -> int:
         """
         Return the number of tetrahedra in the triangulation.
 
@@ -1125,7 +1125,7 @@ cdef class Triangulation():
             return 0
         return get_num_tetrahedra(self.c_triangulation)
 
-    def dehn_fill(self, filling_data, which_cusp=None):
+    def dehn_fill(self, filling_data, which_cusp=None) -> None:
         """
         Set the Dehn filling coefficients of the cusps.  This can be
         specified in the following ways, where the cusps are numbered
@@ -1157,7 +1157,7 @@ cdef class Triangulation():
           >>> N
           m004(-3,4)
 
-        Does not return a new Triangulation.
+        Does not return a new :class:`Triangulation`.
         """
         if self.c_triangulation is NULL:
             raise ValueError('The Triangulation is empty.')
@@ -1421,11 +1421,9 @@ cdef class Triangulation():
             v += 1
         return ans
 
-    def gluing_equations_pgl(self, N=2, equation_type='all'):
+    def gluing_equations_pgl(self, N : int =2, equation_type='all'):
 
         """
-        M.gluing_equations_pgl(N = 2, equation_type='all')
-
         Returns a NeumannZagierTypeEquations object that contains a matrix
         encoding the gluing equations for boundary-parabolic PGL(N,C)
         representations together with explanations of the meaning
@@ -1437,7 +1435,7 @@ cdef class Triangulation():
         "Gluing Equations for PGL(n,C)-Representations of 3-Manifolds"
         (http://arxiv.org/abs/1207.6711).
 
-        The result of the traditional gluing_equations() can be obtained from
+        The result of the :meth:`gluing_equations` can be obtained from
         the general method by:
 
         >>> M = Triangulation('m004')
@@ -1463,17 +1461,21 @@ cdef class Triangulation():
         The first row of the matrix means that the edge equation for
         edge 0 is
 
-           z_0000_0 ^ 2 * zp_0000_0 * z_0000_1 * zpp_0000_1 ^ 2 = 1.
+        .. math::
+
+           {z_{0000,0}}^2 * z'_{0000,0} * z_{0000,1} * {z''_{0000,1}}^2 = 1.
 
         Similarly, the next row encodes the edge equation for the other edge
         and the next two rows encode peripheral equations.
 
-        Following the SnapPy convention, a z denotes the cross ratio z at the
-        edge (0,1), a zp the cross ratio z' at the edge (0,2) and a zpp the cross
-        ratio z" at the edge (1,2). The entire symbol z_xxxx_y then
+        Following the SnapPy convention, a ``z`` denotes the cross ratio
+        :math:`z` at the edge (0,1), a ``zp`` the cross ratio :math:`z'` at
+        the edge (0,2) and a ``zpp`` the cross
+        ratio :math:`z''` at the edge (1,2). The entire symbol ``z_xxxx_y`` then
         denotes the cross ratio belonging to the subsimplex at integral
-        point xxxx (always 0000 for N = 2) of the simplex y. Note: the
-        SnapPy convention is different from the paper
+        point ``xxxx`` (always ``0000`` for ``N = 2``) of the simplex ``y``.
+
+        Note: the SnapPy convention is different from the paper
         mentioned above, e.g., compare
         kernel_code/edge_classes.c with Figure 3. We follow the SnapPy
         convention here so that all computations done in SnapPy are
@@ -1487,19 +1489,19 @@ cdef class Triangulation():
         ['z_0000_0', 'zp_0000_0', 'zpp_0000_0', 'z_0000_1', 'zp_0000_1', 'zpp_0000_1']
 
         A subset of all gluing equations can be obtained by setting the
-        equation_type:
+        ``equation_type``:
 
-        * all gluing equations: 'all'
-        * non-peripheral equations: 'non_peripheral'
+        * all gluing equations: ``all``
+        * non-peripheral equations: ``non_peripheral``
 
-          * edge gluing equations: 'edge'
-          * face gluing equations: 'face'
-          * internal gluing equations: 'internal'
+          * edge gluing equations: ``edge``
+          * face gluing equations: ``face``
+          * internal gluing equations: ``internal``
 
-        * cusp gluing equations: 'peripheral'
+        * cusp gluing equations: ``peripheral``
 
-          * cusp gluing equations for meridians: 'meridian'
-          * cusp gluing equations for longitudes: 'longitude'
+          * cusp gluing equations for meridians: ``meridian``
+          * cusp gluing equations for longitudes: ``longitude``
         """
 
         cdef Integer_matrix_with_explanations c_matrix
@@ -2359,13 +2361,12 @@ cdef class Triangulation():
 
     def cover(self, permutation_rep):
         """
-        Returns a Triangulation representing the finite cover
-        specified by a transitive permutation representation.  The
-        representation is specified by a list of permutations, one for
-        each generator of the simplified presentation of the
-        fundamental group.  Each permutation is specified as a list P
-        such that set(P) == set(range(d)) where d is the degree of the
-        cover.
+        Returns a :class:`Triangulation` representing the finite cover specified
+        by a transitive permutation representation.  The representation is
+        specified by a list of permutations, one for each generator of the
+        simplified presentation of the fundamental group.  Each permutation is
+        specified as a list ``P`` such that ``set(P) == set(range(d))`` where
+        ``d`` is the degree of the cover.
 
         >>> M = Triangulation('m004')
         >>> N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]])
@@ -2379,10 +2380,10 @@ cdef class Triangulation():
         5
 
         Within Sage the permutations can also be of type
-        PermutationGroupElement, in which case they act on the set
-        range(1, d + 1).  Or, you can specify a GAP or Magma subgroup
-        of the fundamental group.  For examples, see the docstring for
-        Manifold.cover
+        ``PermutationGroupElement``, in which case they act on the set
+        ``range(1, d + 1)``.  Or, you can specify a GAP or Magma subgroup
+        of the fundamental group.  For more examples, see the docstring for
+        :meth:`Manifold.cover`.
         """
         cdef RepresentationIntoSn* c_representation
         cdef c_Triangulation* c_triangulation
@@ -2459,8 +2460,6 @@ cdef class Triangulation():
 
     def covers(self, degree, method=None, cover_type='all'):
         """
-        M.covers(degree, method=None, cover_type='all')
-
         Returns a list of Triangulations corresponding to all of the
         finite covers of the given degree.  The default method is
         'low_index' for general covers and 'snappea' for cyclic
@@ -2859,9 +2858,9 @@ cdef class Triangulation():
                 raise ValueError('The peripheral data %s is not acceptable.' %
                                  peripheral_data)
 
-    def has_finite_vertices(self):
+    def has_finite_vertices(self) -> bool:
         """
-        Returns True if and only if the triangulation has finite (non-ideal)
+        Returns ``True`` if and only if the triangulation has finite (non-ideal)
         vertices.
 
         >>> T = Triangulation("m004")

python/cusps/cusp_area_matrix.py

@@ -48,8 +48,7 @@ def cusp_area_matrix(manifold, method='trigDependentTryCanonize',
         [ 7.0000000000000000? 21.4375000000000000?  7.0000000000000000?]
         [ 7.0000000000000000?  7.0000000000000000? 21.4375000000000000?]
 
-    For expert users
-    ----------------
+    **For expert users**
 
     Besides the two values above, ``method`` can be ``trigDependent``:
     this result is also fast to compute by making the assumption that

python/ptolemy/manifoldMethods.py

@@ -26,7 +26,7 @@ def get_ptolemy_obstruction_classes(manifold):
     s_f_t takes values +/-1 and is the value of evaluating the cocycle on
     face f of tetrahedron t.
 
-    === Examples ===
+    **Examples**
 
     Get the obstruction classes for 4_1:
 
@@ -172,8 +172,9 @@ def compute_solutions(self, *args, **kwargs):
               for p in self ])
 
 
-def get_ptolemy_variety(manifold, N, obstruction_class=None,
-                        simplify=True, eliminate_fixed_ptolemys=False):
+def get_ptolemy_variety(manifold, N, obstruction_class = None,
+                        simplify : bool =True,
+                        eliminate_fixed_ptolemys : bool =False):
     """
     Generates Ptolemy variety as described in
     (1) Garoufalidis, Thurston, Zickert
@@ -187,29 +188,26 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None,
     The variety can be exported to magma or sage and solved there. The
     solutions can be processed to compute invariants. See below.
 
-    === Arguments ===
+    :param N: which SL(N,C) we want the variety.
 
-    N --- which SL(N,C) we want the variety.
+    :param obstruction_class: class from Definition 1.7 of (1).
+        ``None`` for trivial class,
+        a value returned from :meth:`get_ptolemy_obstruction_classes`,
+        an integer indexing the obstruction classes returned from
+        :meth:`get_ptolemy_obstruction_classes`,
+        or 'all' to return a list of Ptolemy varieties, one for each
+        obstruction class.
 
-    obstruction_class --- class from Definition 1.7 of (1).
-    None for trivial class or a value returned from get_ptolemy_obstruction_classes.
-    Short cuts: obstruction_class = 'all' returns a list of Ptolemy varieties
-    for each obstruction. For easier iteration, can set obstruction_class to
-    an integer.
+    :param simplify: indicate whether to simplify the equations which
+          significantly reduces the number of variables. Simplifying means that several identified Ptolemy coordinates :math:`x = y = z = ...`
+         are eliminated instead of adding relations :math:`x - y = 0, y - z = 0, ...`
 
-    simplify --- boolean to indicate whether to simplify the equations which
-    significantly reduces the number of variables.
-    Simplifying means that several identified Ptolemy coordinates x = y = z = ...
-    are eliminated instead of adding relations x - y = 0, y - z = 0, ...
-    Defaults to True.
+    :param eliminate_fixed_ptolemys: boolean to indicate whether to eliminate
+       the Ptolemy coordinates that are set to 1 for fixing the decoration.
+       Even though this simplifies the resulting representation, setting it to
+       ``True`` can cause magma to run longer when finding a Groebner basis.
 
-    eliminate_fixed_ptolemys --- boolean to indicate whether to eliminate
-    the Ptolemy coordinates that are set to 1 for fixing the decoration.
-    Even though this simplifies the resulting representation, setting it to
-    True can cause magma to run longer when finding a Groebner basis.
-    Defaults to False.
-
-    === Examples for 4_1 ===
+    **Examples for 4_1**
 
     >>> from snappy import Manifold
     >>> M = Manifold("4_1")
@@ -248,7 +246,7 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None,
 
 
 
-    === If you have a magma installation ===
+    **If you have a magma installation**
 
     Call p.compute_solutions() to automatically call magma on the above output
     and produce exact solutions!!!
@@ -258,7 +256,7 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None,
     ... except:
     ...     sols = None     # magma failed, use precomputed output instead
 
-    === If you do not have a magma installation ===
+    **If you do not have a magma installation**
 
     Load a precomputed example from magma which is provided with the package:
 
@@ -282,7 +280,7 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None,
     >>> if sols is None:    # calling magma failed, so use precomputed example
     ...     sols = solutions_from_magma(_magma_output_for_4_1__sl3)
 
-    === Continue here whether you have or do not have magma ===
+    **Continue here whether you have or do not have magma**
 
     Pick the first solution of the three different solutions (up to Galois
     conjugates):
@@ -306,7 +304,7 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None,
     >>> len(simplified.equations), len(full.equations)
     (24, 72)
 
-    === ONLY DOCTESTS, NOT PART OF DOCUMENTATION ===
+    **ONLY DOCTESTS, NOT PART OF DOCUMENTATION**
 
     >>> varieties = get_ptolemy_variety(M, N = 2, obstruction_class = "all", eliminate_fixed_ptolemys = True)
 

python/snap/nsagetools.py

@@ -332,7 +332,8 @@ def alexander_polynomial(manifold, **kwargs):
         sage: N.alexander_polynomial()
         a^2*b + a*b^2 + a*b + a + b
 
-    Any provided keyword arguments are passed to fundamental_group and
+    Any provided keyword arguments are passed to
+    :meth:`fundamental_group <snappy.Triangulation.fundamental_group>` and
     so affect the group presentation used in the computation.
     """
     if manifold.homology().order() != 'infinite':