gh-37346: sage.schemes.generic: fix docs

Fix various docs problems.

I also removed the `SchemeRationalPoint` class entirely since it is not
used anywhere in the entire Sage library. If anyone oppose this please
notify me!

URL: #37346
Reported by: grhkm21
Reviewer(s): Kwankyu Lee

build/pkgs/configure/checksums.ini

@@ -1,4 +1,4 @@
 tarball=configure-VERSION.tar.gz
-sha1=f4a7dd60c09ac2f3e1f8e388cbf2a527dcd5547c
-md5=c16cb118d9ad6a495f6c5d509b2ec570
-cksum=3417350968
+sha1=f7b6730426fe857cb7036a0daae23aca7cb03dec
+md5=e6d2b686e56ef1e5ecb5f248255870f7
+cksum=3124816602

build/pkgs/configure/package-version.txt

@@ -1 +1 @@
-ab1a517b64b02bf15bbcb8d7c2d4d643bd5eff9b
+1db16f5f41fb1fa9cc6c6e4506d2a44d931d3dbe

src/sage/schemes/generic/glue.py

@@ -16,19 +16,35 @@ class GluedScheme(scheme.Scheme):
     INPUT:
 
 
-    -  ``f`` - open immersion from a scheme U to a scheme
-       X
+    -  ``f`` -- open immersion from a scheme `U` to a scheme
+       `X`
 
-    -  ``g`` - open immersion from U to a scheme Y
+    -  ``g`` -- open immersion from `U` to a scheme `Y`
 
 
-    OUTPUT: The scheme obtained by gluing X and Y along the open set
-    U.
+    OUTPUT: The scheme obtained by gluing `X` and `Y` along the open set
+    `U`.
 
-    .. note::
+    .. NOTE::
 
        Checking that `f` and `g` are open
        immersions is not implemented.
+
+    EXAMPLES::
+
+        sage: R.<x, y> = QQ[]
+        sage: S.<xbar, ybar> = R.quotient(x * y - 1)
+        sage: Rx = QQ["x"]
+        sage: Ry = QQ["y"]
+        sage: phi_x = Rx.hom([xbar])
+        sage: phi_y = Ry.hom([ybar])
+        sage: Sx = Schemes()(phi_x)
+        sage: Sy = Schemes()(phi_y)
+        sage: Sx.glue_along_domains(Sy)
+        Scheme obtained by gluing X and Y along U, where
+          X: Spectrum of Univariate Polynomial Ring in x over Rational Field
+          Y: Spectrum of Univariate Polynomial Ring in y over Rational Field
+          U: Spectrum of Quotient of Multivariate Polynomial Ring in x, y over Rational Field by the ideal (x*y - 1)
     """
     def __init__(self, f, g, check=True):
         if check:
@@ -42,6 +58,23 @@ def __init__(self, f, g, check=True):
         self.__g = g
 
     def gluing_maps(self):
+        r"""
+        Return the gluing maps of this glued scheme, i.e. the maps `f` and `g`.
+
+        EXAMPLES::
+
+            sage: R.<x, y> = QQ[]
+            sage: S.<xbar, ybar> = R.quotient(x * y - 1)
+            sage: Rx = QQ["x"]
+            sage: Ry = QQ["y"]
+            sage: phi_x = Rx.hom([xbar])
+            sage: phi_y = Ry.hom([ybar])
+            sage: Sx = Schemes()(phi_x)
+            sage: Sy = Schemes()(phi_y)
+            sage: Sxy = Sx.glue_along_domains(Sy)
+            sage: Sxy.gluing_maps() == (Sx, Sy)
+            True
+        """
         return self.__f, self.__g
 
     def _repr_(self):

src/sage/schemes/generic/homset.py

@@ -2,13 +2,13 @@
 Set of homomorphisms between two schemes
 
 For schemes `X` and `Y`, this module implements the set of morphisms
-`Hom(X,Y)`. This is done by :class:`SchemeHomset_generic`.
+`\mathrm{Hom}(X,Y)`. This is done by :class:`SchemeHomset_generic`.
 
-As a special case, the Hom-sets can also represent the points of a
-scheme. Recall that the `K`-rational points of a scheme `X` over `k`
-can be identified with the set of morphisms `Spec(K) \to X`. In Sage
-the rational points are implemented by such scheme morphisms. This is
-done by :class:`SchemeHomset_points` and its subclasses.
+As a special case, the Hom-sets can also represent the points of a scheme.
+Recall that the `K`-rational points of a scheme `X` over `k` can be identified
+with the set of morphisms `\mathrm{Spec}(K) \to X`. In Sage the rational points
+are implemented by such scheme morphisms. This is done by
+:class:`SchemeHomset_points` and its subclasses.
 
 .. note::
 
@@ -407,12 +407,12 @@ def _element_constructor_(self, x, check=True):
 # *******************************************************************
 
 class SchemeHomset_points(SchemeHomset_generic):
-    """
+    r"""
     Set of rational points of the scheme.
 
-    Recall that the `K`-rational points of a scheme `X` over `k` can
-    be identified with the set of morphisms `Spec(K) \to X`. In Sage,
-    the rational points are implemented by such scheme morphisms.
+    Recall that the `K`-rational points of a scheme `X` over `k` can be
+    identified with the set of morphisms `\mathrm{Spec}(K) \to X`. In Sage, the
+    rational points are implemented by such scheme morphisms.
 
     If a scheme has a finite number of points, then the homset is
     supposed to implement the Python iterator interface. See
@@ -659,13 +659,13 @@ def _element_constructor_(self, *v, **kwds):
         return self.extended_codomain()._point(self, v, **kwds)
 
     def extended_codomain(self):
-        """
+        r"""
         Return the codomain with extended base, if necessary.
 
         OUTPUT:
 
         The codomain scheme, with its base ring extended to the
-        codomain. That is, the codomain is of the form `Spec(R)` and
+        codomain. That is, the codomain is of the form `\mathrm{Spec}(R)` and
         the base ring of the domain is extended to `R`.
 
         EXAMPLES::
@@ -716,8 +716,8 @@ def _repr_(self):
         return 'Set of rational points of '+str(self.extended_codomain())
 
     def value_ring(self):
-        """
-        Return `R` for a point Hom-set `X(Spec(R))`.
+        r"""
+        Return `R` for a point Hom-set `X(\mathrm{Spec}(R))`.
 
         OUTPUT:
 

src/sage/schemes/generic/morphism.py

@@ -28,12 +28,12 @@
   new Hom-set class does not use ``MyScheme._morphism`` then you
   do not have to provide it.
 
-Note that points on schemes are morphisms `Spec(K)\to X`, too. But we
-typically use a different notation, so they are implemented in a
-different derived class. For this, you should implement a method
+Note that points on schemes are morphisms `\mathrm{Spec}(K)\to X`, too. But we
+typically use a different notation, so they are implemented in a different
+derived class. For this, you should implement a method
 
-* ``MyScheme._point(*args, **kwds)`` returning a point, that is,
-  a morphism `Spec(K)\to X`. Your point class should derive from
+* ``MyScheme._point(*args, **kwds)`` returning a point, that is, a morphism
+  `\mathrm{Spec}(K)\to X`. Your point class should derive from
   :class:`SchemeMorphism_point`.
 
 Optionally, you can also provide a special Hom-set for the points, for
@@ -1790,11 +1790,11 @@ def __init__(self, X):
 ############################################################################
 
 class SchemeMorphism_point(SchemeMorphism):
-    """
+    r"""
     Base class for rational points on schemes.
 
     Recall that the `K`-rational points of a scheme `X` over `k` can
-    be identified with the set of morphisms `Spec(K) \to X`. In Sage,
+    be identified with the set of morphisms `\mathrm{Spec}(K) \to X`. In Sage,
     the rational points are implemented by such scheme morphisms.
 
     EXAMPLES::

src/sage/schemes/generic/point.py

@@ -227,28 +227,3 @@ def _richcmp_(self, other, op):
             False
         """
         return richcmp(self.__P, other.__P, op)
-
-########################################################
-# Points on a scheme defined by a morphism
-########################################################
-
-def is_SchemeRationalPoint(x):
-    return isinstance(x, SchemeRationalPoint)
-
-class SchemeRationalPoint(SchemePoint):
-    def __init__(self, f):
-        """
-        INPUT:
-
-
-        -  ``f`` - a morphism of schemes
-        """
-        SchemePoint.__init__(self, f.codomain(), parent=f.parent())
-        self.__f = f
-
-    def _repr_(self):
-        return "Point on %s defined by the morphism %s" % (self.scheme(),
-                                                         self.morphism())
-
-    def morphism(self):
-        return self.__f

src/sage/schemes/generic/scheme.py

@@ -77,7 +77,7 @@ class Scheme(Parent):
         sage: ProjectiveSpace(4, QQ).category()
         Category of schemes over Rational Field
 
-    There is a special and unique `Spec(\ZZ)` that is the default base
+    There is a special and unique `\mathrm{Spec}(\ZZ)` that is the default base
     scheme::
 
         sage: Spec(ZZ).base_scheme() is Spec(QQ).base_scheme()
@@ -267,7 +267,7 @@ def __call__(self, *args):
 
     @cached_method
     def point_homset(self, S=None):
-        """
+        r"""
         Return the set of S-valued points of this scheme.
 
         INPUT:
@@ -276,7 +276,7 @@ def point_homset(self, S=None):
 
         OUTPUT:
 
-        The set of morphisms `Spec(S)\to X`.
+        The set of morphisms `\mathrm{Spec}(S) \to X`.
 
         EXAMPLES::