Improve the headings of the databases section of the reference manual

src/doc/en/reference/databases/index.rst

@@ -1,68 +1,40 @@
 Databases
 =========
 
-There are numerous specific mathematical databases either included
-in Sage or available as optional packages. Also, Sage includes two
-powerful general database packages.
+Sage includes mathematical databases as standard or optional packages,
+and provides convenient interfaces for easy access to the databases.
 
-Sage includes the ZOPE object oriented database ZODB, which
-"is a Python object persistence system. It provides transparent object-oriented persistency."
+Standard databases
+------------------
 
-Sage also includes the powerful relational database SQLite, along
-with a Python interface to SQLite. SQlite is a small C library that
-implements a self-contained, embeddable, zero-configuration SQL
-database engine.
+These databases are available in the standard install of Sage or if Sage can access
+Internet.
 
+.. toctree::
+   :maxdepth: 1
 
--  Transactions are atomic, consistent, isolated, and durable
-   (ACID) even after system crashes and power failures.
-
--  Zero-configuration - no setup or administration needed.
-
--  Implements most of SQL92. (Features not supported)
-
--  A complete database is stored in a single disk file.
-
--  Database files can be freely shared between machines with
-   different byte orders.
-
--  Supports databases up to 2 tebibytes (2^41 bytes) in size.
-
--  Strings and BLOBs up to 2 gibibytes (2^31 bytes) in size.
-
--  Small code footprint: less than 250KiB fully configured or less
-   than 150KiB with optional features omitted.
-
--  Faster than popular client/server database engines for most
-   common operations.
-
--  Simple, easy to use API.
-
--  TCL bindings included. Bindings for many other languages
-   available separately.
-
--  Well-commented source code with over 95% test coverage.
+   sage/databases/conway
+   sage/databases/oeis
+   sage/databases/sloane
+   sage/databases/findstat
 
--  Self-contained: no external dependencies.
+Optional databases
+------------------
 
--  Sources are in the public domain. Use for any purpose.
+The following databases require you to install optional packages before full access.
 
 .. toctree::
    :maxdepth: 1
 
+   sage/databases/cunningham_tables
+   sage/databases/knotinfo_db
+   sage/databases/cubic_hecke_db
+   sage/databases/symbolic_data
    sage/databases/cremona
    sage/databases/stein_watkins
    sage/databases/jones
-   sage/databases/oeis
-   sage/databases/sloane
-   sage/databases/findstat
-   sage/databases/conway
-   sage/databases/odlyzko
-   sage/databases/symbolic_data
-   sage/databases/cunningham_tables
    sage/databases/db_class_polynomials
    sage/databases/db_modular_polynomials
-   sage/databases/knotinfo_db
-   sage/databases/cubic_hecke_db
+   sage/databases/odlyzko
 
 .. include:: ../footer.txt

src/sage/databases/cubic_hecke_db.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 r"""
-Cubic Hecke Database
+Cubic Hecke database
 
 This module contains the class :class:`CubicHeckeDataBase` which serves as an
 interface to `Ivan Marin's data files
@@ -31,10 +31,24 @@
 of linear forms on the cubic Hecke algebra on at most four strands
 satisfying the Markov trace condition for its cubic Hecke subalgebras.
 
+To use the database, you need to install the optional package by the Sage
+command ::
+
+    sage -i database_cubic_hecke
+
+EXAMPLES::
+
+    sage: # optional - database_cubic_hecke
+    sage: from sage.databases.cubic_hecke_db import CubicHeckeDataBase
+    sage: cha_db = CubicHeckeDataBase()
+    sage: cha_db
+    <sage.databases.cubic_hecke_db.CubicHeckeDataBase object at ...>
+
 AUTHORS:
 
-- Sebastian Oehms (May 2020): initial version
-- Sebastian Oehms (March 2022): PyPi version and Markov trace functionality
+- Sebastian Oehms (2020-05): initial version
+- Sebastian Oehms (2022-03): PyPi version and Markov trace functionality
+
 """
 
 ##############################################################################

src/sage/databases/cunningham_tables.py

@@ -1,5 +1,18 @@
 r"""
-Cunningham table
+Cunningham tables
+
+This module provides :func:`cunningham_prime_factors`, which lists the prime
+numbers occurring in the factorization of numbers of type `b^n+1` or `b^n-1`
+with `b \in \{2,3,5,6,7,10,11,12\}`. For an introduction to Cunningham prime
+factors, see :wikipedia:`Cunningham_Project`. The data becomes available if you
+install the optional package by the command ::
+
+    sage -i cunningham_tables
+
+AUTHORS:
+
+- Yann Laigle-Chapuy (2009-10-18): initial version
+
 """
 
 import os
@@ -16,12 +29,25 @@ def cunningham_prime_factors():
 
     They occur in the factorization of numbers of type `b^n+1` or `b^n-1` with `b \in \{2,3,5,6,7,10,11,12\}`.
 
-    Data from http://cage.ugent.be/~jdemeyer/cunningham/
+    EXAMPLES::
+
+        sage: # optional - cunningham_tables
+        sage: from sage.databases.cunningham_tables import cunningham_prime_factors
+        sage: cunningham_prime_factors()
+        [2,
+         3,
+         5,
+         7,
+         11,
+         13,
+         17,
+         ...
     """
     file = os.path.join(SAGE_SHARE,'cunningham_tables','cunningham_prime_factors.sobj')
     if os.path.exists(file):
         return [Integer(_) for _ in load(file)]
     else:
         from warnings import warn
-        warn("You might consider installing the optional package for factoring Cunningham numbers with the following command: ``sage -i cunningham_tables``")
+        warn("You might consider installing the optional package for factoring Cunningham numbers"
+             " with the following command: ``sage -i cunningham_tables``")
         return []

src/sage/databases/db_class_polynomials.py

@@ -1,5 +1,22 @@
 """
-Database of Hilbert Polynomials
+Database of Hilbert polynomials
+
+This module gives access to the database of Hilbert class polynomials. To use the database, you need to install
+the optional package by the Sage command ::
+
+    sage -i database_kohel
+
+EXAMPLES::
+
+    sage: # optional - database_kohel
+    sage: db = HilbertClassPolynomialDatabase()
+    sage: db[32]
+    x^2 - 52250000*x + 12167000000
+
+AUTHORS:
+
+- David Kohel (2006-08-04): initial version
+
 """
 # ****************************************************************************
 #       Copyright (C) 2006 David Kohel <kohel@maths.usyd.edu.au>
@@ -45,8 +62,9 @@ def __getitem__(self, disc):
         r"""
         TESTS::
 
+            sage: # optional - database_kohel
             sage: db = HilbertClassPolynomialDatabase()
-            sage: db[32]  # optional - database_kohel
+            sage: db[32]
             x^2 - 52250000*x + 12167000000
             sage: db[123913912]
             Traceback (most recent call last):
@@ -66,16 +84,17 @@ class HilbertClassPolynomialDatabase(ClassPolynomialDatabase):
 
     EXAMPLES::
 
+        sage: # optional - database_kohel
         sage: db = HilbertClassPolynomialDatabase()
-        sage: db[-4]                     # optional - database_kohel
+        sage: db[-4]
         x - 1728
-        sage: db[-7]                     # optional - database_kohel
+        sage: db[-7]
         x + 3375
-        sage: f = db[-23]; f             # optional - database_kohel
+        sage: f = db[-23]; f
         x^3 + 3491750*x^2 - 5151296875*x + 12771880859375
-        sage: f.discriminant().factor()  # optional - database_kohel
+        sage: f.discriminant().factor()
         -1 * 5^18 * 7^12 * 11^4 * 17^2 * 19^2 * 23
-        sage: db[-23]                    # optional - database_kohel
+        sage: db[-23]
         x^3 + 3491750*x^2 - 5151296875*x + 12771880859375
     """
     model = "Cls"

src/sage/databases/db_modular_polynomials.py

@@ -1,5 +1,25 @@
 """
-Database of Modular Polynomials
+Database of modular polynomials
+
+This module gives access to the database of modular polynomials. To use the
+database, you need to install the optional package by the Sage command ::
+
+    sage -i database_kohel
+
+EXAMPLES::
+
+    sage: # optional - database_kohel
+    sage: DBMP = ClassicalModularPolynomialDatabase()
+    sage: f = DBMP[29]
+    sage: f.degree()
+    58
+    sage: f.coefficient([28,28])
+    400152899204646997840260839128
+
+AUTHORS:
+
+- David Kohel (2006-08-04): initial version
+
 """
 # ****************************************************************************
 #       Copyright (C) 2006 William Stein <wstein@gmail.com>
@@ -48,8 +68,9 @@ def _dbz_to_integer_list(name):
     r"""
     TESTS::
 
+        sage: # optional - database_kohel
         sage: from sage.databases.db_modular_polynomials import _dbz_to_integer_list
-        sage: _dbz_to_integer_list('PolMod/Atk/pol.002.dbz') # optional - database_kohel
+        sage: _dbz_to_integer_list('PolMod/Atk/pol.002.dbz')
         [[3, 0, 1],
          [2, 1, -1],
          [2, 0, 744],
@@ -58,9 +79,9 @@ def _dbz_to_integer_list(name):
          [0, 2, 1],
          [0, 1, 7256],
          [0, 0, 15252992]]
-        sage: _dbz_to_integer_list('PolMod/Cls/pol.001.dbz') # optional - database_kohel
+        sage: _dbz_to_integer_list('PolMod/Cls/pol.001.dbz')
         [[1, 0, 1]]
-        sage: _dbz_to_integer_list('PolMod/Eta/pol.002.dbz') # optional - database_kohel
+        sage: _dbz_to_integer_list('PolMod/Eta/pol.002.dbz')
         [[3, 0, 1], [2, 0, 48], [1, 1, -1], [1, 0, 768], [0, 0, 4096]]
     """
     from sage.rings.integer import Integer
@@ -130,14 +151,14 @@ def __getitem__(self, level):
 
         EXAMPLES::
 
+            sage: # optional - database_kohel
             sage: DBMP = ClassicalModularPolynomialDatabase()
-            sage: f = DBMP[29]                                 # optional - database_kohel
-            sage: f.degree()                                   # optional - database_kohel
+            sage: f = DBMP[29]
+            sage: f.degree()
             58
-            sage: f.coefficient([28,28])                       # optional - database_kohel
+            sage: f.coefficient([28,28])
             400152899204646997840260839128
-
-            sage: DBMP[50]                                     # optional - database_kohel
+            sage: DBMP[50]
             Traceback (most recent call last):
             ...
             ValueError: file not found in the Kohel database