Merge pull request #209 from saraedum/links

Check for broken references in the documentation

.github/workflows/doc.yml

@@ -31,7 +31,7 @@ jobs:
         shell: bash -l {0}
         run: |
           cd doc
-          make html SPHINXOPTS="-W"
+          make html SPHINXOPTS="-W -n --keep-going"
           # Do not run Jekyll to create GitHub Pages but take HTML files as they are.
           touch _build/html/.nojekyll
       - name: provide documentation as artifact for netlify workflow

doc/conf.py

@@ -7,6 +7,7 @@
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
     'myst_nb',
 ]
 
@@ -24,7 +25,7 @@
 
 # General information about the project.
 project = u'sage-flatsurf'
-copyright = u'2016-2022, the sage-flatsurf authors'
+copyright = u'2016-2023, the sage-flatsurf authors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -35,6 +36,9 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build', 'news']
 
+# Allow linking to external projects, e.g., SageMath
+intersphinx_mapping = {'sage': ('https://doc.sagemath.org/html/en/reference', None)}
+
 # -- Options for HTML output ----------------------------------------------
 
 # Imitate the look of the SageMath documentation.

doc/geometry/hyperbolic.rst

@@ -4,3 +4,5 @@
 .. automodule:: flatsurf.geometry.hyperbolic
    :members:
    :undoc-members:
+   :special-members:
+   :private-members:

doc/geometry/surface.rst

@@ -4,3 +4,4 @@
 .. automodule:: flatsurf.geometry.surface
    :members:
    :undoc-members:
+   :private-members:

doc/news/links.rst

@@ -0,0 +1,3 @@
+**Fixed:**
+
+* Fixed broken links in the documentation.

flatsurf/geometry/finitely_generated_matrix_group.py

@@ -32,6 +32,7 @@
 # ****************************************************************************
 #       Copyright (C) 2013-2019 Vincent Delecroix <[email protected]>
 #                     2013-2019 W. Patrick Hooper <[email protected]>
+#                     2023 Julian Rüth <[email protected]>
 #
 #  Distributed under the terms of the GNU General Public License (GPL)
 #  as published by the Free Software Foundation; either version 2 of
@@ -203,6 +204,12 @@ def matrix_multiplicative_order(m):
 class FinitelyGenerated2x2MatrixGroup(Group):
     r"""
     Finitely generated group of 2x2 matrices with real coefficients
+
+    .. SEEALSO::
+
+        :py:mod:`sage.groups.group` for the general interface of groups
+        like this in SageMath
+
     """
     def __init__(self, matrices, matrix_space=None, category=None):
         if matrix_space is None:
@@ -362,7 +369,29 @@ def __reduce__(self):
     def one(self):
         return self._matrix_space.identity_matrix()
 
-    def an_element(self):
+    def _an_element_(self):
+        r"""
+        Return a typical element of this group, namely a generator.
+
+        EXAMPLES:
+
+            sage: from flatsurf.geometry.finitely_generated_matrix_group import FinitelyGenerated2x2MatrixGroup
+            sage: G = FinitelyGenerated2x2MatrixGroup([identity_matrix(2)])
+
+            sage: G._an_element_()
+            [1 0]
+            [0 1]
+
+            sage: G.an_element()
+            [1 0]
+            [0 1]
+
+        .. SEEALSO::
+
+            :meth:`sage.structure.parent.Parent.an_element` which relies on
+            this method and should be called instead
+
+        """
         return self._generators[0]
 
     def gen(self, i):

flatsurf/geometry/half_dilation_surface.py

@@ -1,6 +1,7 @@
 # ****************************************************************************
 #       Copyright (C) 2013-2019 Vincent Delecroix <[email protected]>
 #                     2013-2019 W. Patrick Hooper <[email protected]>
+#                          2023 Julian Rüth <[email protected]>
 #
 #  Distributed under the terms of the GNU General Public License (GPL)
 #  as published by the Free Software Foundation; either version 2 of
@@ -31,7 +32,7 @@ class HalfDilationSurface(SimilaritySurface):
     A half-dilation surface is a (G,X) structure for the group of dilatations
     `G = \RR^*` acting on the plane `X = \RR^2`. If you want to consider only
     the oriented case, have a look at
-    :meth:`flatsurf.dilation_surface.DilationSurface`.
+    :class:`~.dilation_surface.DilationSurface`.
     """
 
     def __rmul__(self,matrix):