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::