Trac #32508: Eliminate use of __init__.py files for supplying package docstrings

... as in `src/sage/categories/__init__.py` or
`src/sage/combinat/__init__.py`

(part of #32501)

URL: https://trac.sagemath.org/32508
Reported by: mkoeppe
Ticket author(s): Kwankyu Lee
Reviewer(s): Matthias Koeppe

Author: Release Manager

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

@@ -1,6 +1,14 @@
 Category Framework
 ==================
 
+Introduction
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   sage/categories
+
 The Sage Category Framework
 ---------------------------
 

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

@@ -3,7 +3,6 @@ Combinatorics
 
 .. automodule:: sage.combinat
 
-
 Comprehensive Module List
 -------------------------
 

src/doc/en/reference/combinat/module_list.rst

@@ -1,4 +1,4 @@
-Comprehensive Module list
+Comprehensive Module List
 =========================
 
 .. NOTE::
@@ -15,7 +15,6 @@ Comprehensive Module list
 .. toctree::
     :maxdepth: 1
 
-    sage/combinat/__init__
     sage/combinat/abstract_tree
     sage/combinat/affine_permutation
     sage/combinat/algebraic_combinatorics
@@ -28,10 +27,9 @@ Comprehensive Module list
     sage/combinat/blob_algebra
     sage/combinat/cartesian_product
     sage/combinat/catalog_partitions
-    sage/combinat/chas/__init__
+    sage/combinat/chas/all
     sage/combinat/chas/fsym
     sage/combinat/chas/wqsym
-    sage/combinat/cluster_algebra_quiver/__init__
     sage/combinat/cluster_algebra_quiver/all
     sage/combinat/cluster_algebra_quiver/cluster_seed
     sage/combinat/cluster_algebra_quiver/mutation_class
@@ -50,7 +48,6 @@ Comprehensive Module list
     sage/combinat/constellation
     sage/combinat/core
     sage/combinat/counting
-    sage/combinat/crystals/__init__
     sage/combinat/crystals/affine
     sage/combinat/crystals/affine_factorization
     sage/combinat/crystals/affinization
@@ -90,7 +87,6 @@ Comprehensive Module list
     sage/combinat/degree_sequences
     sage/combinat/derangements
     sage/combinat/descent_algebra
-    sage/combinat/designs/__init__
     sage/combinat/designs/all
     sage/combinat/designs/bibd
     sage/combinat/designs/resolvable_bibd
@@ -149,22 +145,19 @@ Comprehensive Module list
     sage/combinat/k_tableau
     sage/combinat/kazhdan_lusztig
     sage/combinat/knutson_tao_puzzles
-    sage/combinat/matrices/__init__
     sage/combinat/matrices/all
     sage/combinat/matrices/dancing_links
     sage/combinat/matrices/dlxcpp
     sage/combinat/matrices/hadamard_matrix
     sage/combinat/matrices/latin
     sage/combinat/misc
     sage/combinat/multiset_partition_into_sets_ordered
-    sage/combinat/ncsf_qsym/__init__
     sage/combinat/ncsf_qsym/all
     sage/combinat/ncsf_qsym/combinatorics
     sage/combinat/ncsf_qsym/generic_basis_code
     sage/combinat/ncsf_qsym/ncsf
     sage/combinat/ncsf_qsym/qsym
     sage/combinat/ncsf_qsym/tutorial
-    sage/combinat/ncsym/__init__
     sage/combinat/ncsym/all
     sage/combinat/ncsym/bases
     sage/combinat/ncsym/dual
@@ -190,7 +183,6 @@ Comprehensive Module list
     sage/combinat/perfect_matching
     sage/combinat/permutation
     sage/combinat/permutation_cython
-    sage/combinat/posets/__init__
     sage/combinat/posets/all
     sage/combinat/posets/cartesian_product
     sage/combinat/posets/d_complete
@@ -213,7 +205,6 @@ Comprehensive Module list
     sage/combinat/ribbon
     sage/combinat/ribbon_shaped_tableau
     sage/combinat/ribbon_tableau
-    sage/combinat/rigged_configurations/__init__
     sage/combinat/rigged_configurations/all
     sage/combinat/rigged_configurations/bij_abstract_class
     sage/combinat/rigged_configurations/bij_infinity
@@ -236,7 +227,6 @@ Comprehensive Module list
     sage/combinat/rigged_configurations/rigged_partition
     sage/combinat/rigged_configurations/tensor_product_kr_tableaux
     sage/combinat/rigged_configurations/tensor_product_kr_tableaux_element
-    sage/combinat/root_system/__init__
     sage/combinat/root_system/all
     sage/combinat/root_system/ambient_space
     sage/combinat/root_system/associahedron
@@ -298,7 +288,6 @@ Comprehensive Module list
     sage/combinat/schubert_polynomial
     sage/combinat/set_partition
     sage/combinat/set_partition_ordered
-    sage/combinat/sf/__init__
     sage/combinat/sf/all
     sage/combinat/sf/character
     sage/combinat/sf/classical
@@ -334,7 +323,6 @@ Comprehensive Module list
     sage/combinat/skew_partition
     sage/combinat/skew_tableau
     sage/combinat/sloane_functions
-    sage/combinat/species/__init__
     sage/combinat/species/all
     sage/combinat/species/characteristic_species
     sage/combinat/species/composition_species
@@ -375,9 +363,8 @@ Comprehensive Module list
     sage/combinat/tuple
     sage/combinat/tutorial
     sage/combinat/vector_partition
-    sage/combinat/words/__init__
     sage/combinat/words/abstract_word
-    sage/combinat/words/all
+    sage/combinat/words
     sage/combinat/words/alphabet
     sage/combinat/words/finite_word
     sage/combinat/words/infinite_word

src/sage/categories/__init__.py

@@ -1,29 +0,0 @@
-r"""
-Sage categories quickref
-------------------------
-
-- sage.categories.primer?             A primer on Elements, Parents, and Categories
-- sage.categories.tutorial?           A tutorial on Elements, Parents, and Categories
-- Category?                           Technical background on categories
-- Sets() Semigroups() Algebras(QQ)    Some categories
-- SemiGroups().example()??            Sample implementation of a semigroup
-- Hom(A, B), End(A, Algebras())       Homomorphisms sets
-- tensor, cartesian_product           Functorial constructions
-
-Module layout:
-
-- sage.categories.basic:              the basic categories
-- sage.categories.all:                all categories
-- sage.categories.semigroups:         the Semigroups() category
-- sage.categories.examples.semigroups the example of Semigroups()
-- sage.categories.homset, map,
-                  morphism, functors: morphisms, ...
-- sage.categories.cartesian_product, tensor,
-                  dual:               functorial constructions
-
-
-Todo: put the quickref in quickref.py, and only some pointers here?
-
-"""
-
-from . import primer

src/sage/categories/all.py

@@ -1,3 +1,34 @@
+r"""
+Sage categories quickref
+
+- ``sage.categories.primer?``                      a primer on Elements, Parents, and Categories
+- ``sage.categories.tutorial?``                    a tutorial on Elements, Parents, and Categories
+- ``Category?``                                    technical background on categories
+- ``Sets()``, ``Semigroups()``, ``Algebras(QQ)``   some categories
+- ``SemiGroups().example()??``                     sample implementation of a semigroup
+- ``Hom(A, B)``, ``End(A, Algebras())``            homomorphisms sets
+- ``tensor``, ``cartesian_product``                functorial constructions
+
+Module layout:
+
+- :mod:`sage.categories.basic`                the basic categories
+- :mod:`sage.categories.all`                  all categories
+- :mod:`sage.categories.semigroups`           the ``Semigroups()`` category
+- :mod:`sage.categories.examples.semigroups`  the example of ``Semigroups()``
+- :mod:`sage.categories.homset`               morphisms, ...
+- :mod:`sage.categories.map`
+- :mod:`sage.categories.morphism`
+- :mod:`sage.categories.functors`
+- :mod:`sage.categories.cartesian_product`    functorial constructions
+- :mod:`sage.categories.tensor`
+- :mod:`sage.categories.dual`
+"""
+# install the docstring of this module to the containing package
+from sage.misc.namespace_package import install_doc
+install_doc(__package__, __doc__)
+
+from . import primer
+
 from sage.misc.lazy_import import lazy_import
 
 from .category import Category

src/sage/combinat/__init__.py

@@ -1,49 +0,0 @@
-r"""
-Combinatorics
-=============
-
-Introductory material
----------------------
-
-- :ref:`sage.combinat.quickref`
-- :ref:`sage.combinat.tutorial`
-
-Thematic indexes
-----------------
-
-- :ref:`sage.combinat.algebraic_combinatorics`
-
-  - :ref:`sage.combinat.chas`
-  - :ref:`sage.combinat.cluster_algebra_quiver`
-  - :ref:`sage.combinat.crystals`
-  - :ref:`sage.combinat.root_system`
-  - :ref:`sage.combinat.sf`
-  - :class:`~sage.combinat.fully_commutative_elements.FullyCommutativeElements`
-
-- :ref:`sage.combinat.counting`
-- :ref:`sage.combinat.enumerated_sets`
-- :ref:`sage.combinat.catalog_partitions`
-- :ref:`sage.combinat.finite_state_machine`
-- :ref:`sage.combinat.species`
-- :ref:`sage.combinat.designs`
-- :ref:`sage.combinat.posets`
-- :ref:`sage.combinat.words`
-
-Utilities
----------
-
-- :ref:`sage.combinat.output`
-- :ref:`sage.combinat.ranker`
-- :func:`Combinatorial maps <sage.combinat.combinatorial_map.combinatorial_map>`
-- :ref:`sage.combinat.misc`
-
-Related topics
---------------
-
-- :ref:`sage.coding`
-- :ref:`sage.dynamics`
-- :ref:`sage.graphs`
-
-"""
-from . import quickref
-from . import tutorial

src/sage/combinat/algebraic_combinatorics.py

@@ -1,17 +1,9 @@
 r"""
 Algebraic combinatorics
-=======================
-
-Quickref
---------
-
-.. TODO:: write it!
 
 Thematic tutorials
 ------------------
 
-.. TODO:: get Sphinx to create those cross links properly
-
 - `Algebraic Combinatorics in Sage <../../../../thematic_tutorials/algebraic_combinatorics.html>`_
 - `Lie Methods and Related Combinatorics in Sage <../../../../thematic_tutorials/lie.html>`_
 - `Linear Programming (Mixed Integer) <../../../../thematic_tutorials/linear_programming.html>`_
@@ -41,10 +33,10 @@
 Combinatorial Representation Theory
 -----------------------------------
 
-- :ref:`sage.combinat.root_system`
-- :ref:`sage.combinat.crystals`
-- :ref:`sage.combinat.rigged_configurations`
-- :ref:`sage.combinat.cluster_algebra_quiver`
+- :ref:`sage.combinat.root_system.all`
+- :ref:`sage.combinat.crystals.all`
+- :ref:`sage.combinat.rigged_configurations.all`
+- :ref:`sage.combinat.cluster_algebra_quiver.all`
 - :class:`~sage.combinat.kazhdan_lusztig.KazhdanLusztigPolynomial`
 - :class:`~sage.combinat.symmetric_group_representations.SymmetricGroupRepresentation`
 - :ref:`sage.combinat.yang_baxter_graph`

src/sage/combinat/all.py

@@ -1,6 +1,54 @@
+r"""
+Combinatorics
+
+Introductory material
+---------------------
+
+- :ref:`sage.combinat.quickref`
+- :ref:`sage.combinat.tutorial`
+
+Thematic indexes
+----------------
+
+- :ref:`sage.combinat.algebraic_combinatorics`
+
+  - :ref:`sage.combinat.chas.all`
+  - :ref:`sage.combinat.cluster_algebra_quiver.all`
+  - :ref:`sage.combinat.crystals.all`
+  - :ref:`sage.combinat.root_system.all`
+  - :ref:`sage.combinat.sf.all`
+  - :class:`~sage.combinat.fully_commutative_elements.FullyCommutativeElements`
+
+- :ref:`sage.combinat.counting`
+- :ref:`sage.combinat.enumerated_sets`
+- :ref:`sage.combinat.catalog_partitions`
+- :ref:`sage.combinat.finite_state_machine`
+- :ref:`sage.combinat.species.all`
+- :ref:`sage.combinat.designs.all`
+- :ref:`sage.combinat.posets.all`
+- :ref:`sage.combinat.words`
+
+Utilities
+---------
+
+- :ref:`sage.combinat.output`
+- :ref:`sage.combinat.ranker`
+- :func:`Combinatorial maps <sage.combinat.combinatorial_map.combinatorial_map>`
+- :ref:`sage.combinat.misc`
+
+Related topics
+--------------
+
+- :ref:`sage.coding`
+- :ref:`sage.dynamics`
+- :ref:`sage.graphs`
+
 """
-Combinatorics features that are imported by default in the interpreter namespace
-"""
+# install the docstring of this module to the containing package
+from sage.misc.namespace_package import install_doc
+install_doc(__package__, __doc__)
+
+from . import quickref, tutorial
 
 from sage.misc.lazy_import import lazy_import
 

src/sage/combinat/catalog_partitions.py

@@ -1,6 +1,5 @@
 r"""
 Enumerated sets of partitions, tableaux, ...
-============================================
 
 Partitions
 ----------

src/sage/combinat/chas/__init__.py

@@ -1,13 +1 @@
-"""
-Combinatorial Hopf algebras
-===========================
 
-- :ref:`sage.combinat.sf`
-- :ref:`sage.combinat.ncsf_qsym`
-- :ref:`sage.combinat.ncsym`
-- :ref:`sage.combinat.schubert_polynomial`
-- :ref:`sage.combinat.chas.fsym`
-- :ref:`sage.combinat.fqsym`
-- :ref:`sage.combinat.grossman_larson_algebras`
-- :ref:`sage.combinat.chas.wqsym`
-"""

src/sage/combinat/chas/all.py

@@ -1,7 +1,21 @@
 """
-Combinatorial Hopf Algebras
+Combinatorial Hopf algebras
+
+- :ref:`sage.combinat.sf.all`
+- :ref:`sage.combinat.ncsf_qsym.all`
+- :ref:`sage.combinat.ncsym.all`
+- :ref:`sage.combinat.schubert_polynomial`
+- :ref:`sage.combinat.chas.fsym`
+- :ref:`sage.combinat.fqsym`
+- :ref:`sage.combinat.grossman_larson_algebras`
+- :ref:`sage.combinat.chas.wqsym`
 """
+# install the docstring of this module to the containing package
+from sage.misc.namespace_package import install_doc
+install_doc(__package__, __doc__)
+
 from sage.misc.lazy_import import lazy_import
 
 lazy_import('sage.combinat.chas.fsym', ['FreeSymmetricFunctions'])
 lazy_import('sage.combinat.chas.wqsym', ['WordQuasiSymmetricFunctions'])
+

src/sage/combinat/cluster_algebra_quiver/__init__.py

@@ -1,10 +0,0 @@
-r"""
-Cluster Algebras and Quivers
-============================
-
-- A compendium on the cluster algebra and quiver package in Sage [MS2011]_
-
-- :ref:`sage.combinat.cluster_algebra_quiver.quiver_mutation_type`
-- :ref:`sage.combinat.cluster_algebra_quiver.quiver`
-- :ref:`sage.combinat.cluster_algebra_quiver.cluster_seed`
-"""