Trac #16766: Improve the doc of combinat/designs/

It seems that there will be a release very soon, and it would be a pity
to show a bad doc to the world. Especially when everybody will find our
new design stuff incredible ! `:-P`

(pleasepleasepleaseplease if you can review it fast, help meeeee !!)

Nathann

URL: http://trac.sagemath.org/16766
Reported by: ncohen
Ticket author(s): Nathann Cohen
Reviewer(s): Volker Braun, Dima Pasechnik

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

@@ -1,26 +1,40 @@
 Designs and Incidence Structures
 ================================
 
+All designs can be accessed by ``designs.<tab>`` and are listed in
+the design catalog:
+
 .. toctree::
    :maxdepth: 1
 
-   ../sage/combinat/designs/covering_design
-   ../sage/combinat/designs/ext_rep
-   ../sage/combinat/designs/incidence_structures
    ../sage/combinat/designs/design_catalog
 
-Constructions
--------------
+**Design-related classes**
+
+.. toctree::
+   :maxdepth: 1
+
+   ../sage/combinat/designs/incidence_structures
+   ../sage/combinat/designs/covering_design
+
+**Constructions**
 
 .. toctree::
    :maxdepth: 1
 
    ../sage/combinat/designs/block_design
    ../sage/combinat/designs/bibd
-   ../sage/combinat/designs/steiner_quadruple_systems
    ../sage/combinat/designs/latin_squares
    ../sage/combinat/designs/orthogonal_arrays
    ../sage/combinat/designs/orthogonal_arrays_recursive
    ../sage/combinat/designs/difference_family
+   ../sage/combinat/designs/steiner_quadruple_systems
    ../sage/combinat/designs/database
 
+**Technical things**
+
+.. toctree::
+   :maxdepth: 1
+
+   ../sage/combinat/designs/ext_rep
+   ../sage/combinat/designs/designs_pyx

src/sage/combinat/designs/bibd.py

@@ -1,27 +1,34 @@
 r"""
 Balanced Incomplete Block Designs (BIBD)
 
-This module implements two constructions of Balanced Incomplete Block Designs:
+This module gathers everything related to Balanced Incomplete Block Designs. One can build a
+BIBD (or check that it can be built) with :func:`balanced_incomplete_block_design`::
 
-* Steiner Triple Systems, i.e. `(v,3,1)`-BIBD.
-* `K_4`-decompositions of `K_v`, i.e. `(v,4,1)`-BIBD.
+    sage: BIBD = designs.balanced_incomplete_block_design(7,3)
 
-These BIBD can be obtained through the :func:`balanced_incomplete_block_design`
-method, available in Sage as ``designs.balanced_incomplete_block_design``.
+In particular, Sage can build a `(v,k,1)`-BIBD when one exists for all `k\leq
+5`. The following functions are available:
 
-EXAMPLES::
+It defines the following functions:
 
-    sage: designs.balanced_incomplete_block_design(7,3)
-    Incidence structure with 7 points and 7 blocks
-    sage: designs.balanced_incomplete_block_design(7,3).blocks()
-    [[0, 1, 3], [0, 2, 4], [0, 5, 6], [1, 2, 6], [1, 4, 5], [2, 3, 5], [3, 4, 6]]
-    sage: designs.balanced_incomplete_block_design(13,4).blocks()
-    [[0, 1, 2, 12], [0, 3, 6, 9], [0, 4, 8, 10], [0, 5, 7, 11], [1, 3, 8, 11],
-     [1, 4, 7, 9], [1, 5, 6, 10], [2, 3, 7, 10], [2, 4, 6, 11], [2, 5, 8, 9],
-     [3, 4, 5, 12], [6, 7, 8, 12], [9, 10, 11, 12]]
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
 
-`K_4`-decompositions of `K_v`
------------------------------
+    :func:`balanced_incomplete_block_design` | Return a BIBD of parameters `v,k`.
+    :func:`BIBD_from_TD` | Return a BIBD through TD-based constructions.
+    :func:`BIBD_from_difference_family` | Return the BIBD associated to the difference family ``D`` on the group ``G``.
+    :func:`BIBD_from_PBD` | Return a `(v,k,1)`-BIBD from a `(r,K)`-PBD where `r=(v-1)/(k-1)`.
+    :func:`PBD_from_TD` | Return a `(kt,\{k,t\})`-PBD if `u=0` and a `(kt+u,\{k,k+1,t,u\})`-PBD otherwise.
+    :func:`steiner_triple_system` | Return a Steiner Triple System.
+    :func:`v_5_1_BIBD` | Return a `(v,5,1)`-BIBD.
+    :func:`v_4_1_BIBD` | Return a `(v,4,1)`-BIBD.
+    :func:`PBD_4_5_8_9_12` | Return a `(v,\{4,5,8,9,12\})`-PBD on `v` elements.
+    :func:`BIBD_5q_5_for_q_prime_power` | Return a `(5q,5,1)`-BIBD with `q\equiv 1\pmod 4` a prime power.
+
+
+**Construction of BIBD when** `k=4`
 
 Decompositions of `K_v` into `K_4` (i.e. `(v,4,1)`-BIBD) are built following
 Douglas Stinson's construction as presented in [Stinson2004]_ page 167. It is
@@ -30,8 +37,7 @@
 can always be transformed into a `((k-1)v+1,4,1)`-BIBD, which covers all
 possible cases of `(v,4,1)`-BIBD.
 
-`K_5`-decompositions of `K_v`
------------------------------
+**Construction of BIBD when** `k=5`
 
 Decompositions of `K_v` into `K_4` (i.e. `(v,4,1)`-BIBD) are built following
 Clayton Smith's construction [ClaytonSmith]_.
@@ -54,7 +60,7 @@
 
 def balanced_incomplete_block_design(v,k,existence=False,use_LJCR=False):
     r"""
-    Returns a BIBD of parameters `v,k`.
+    Return a BIBD of parameters `v,k`.
 
     A Balanced Incomplete Block Design of parameters `v,k` is a collection
     `\mathcal C` of `k`-subsets of `V=\{0,\dots,v-1\}` such that for any two
@@ -71,7 +77,7 @@ def balanced_incomplete_block_design(v,k,existence=False,use_LJCR=False):
 
     - ``v,k`` (integers)
 
-    - ``existence`` (boolean) -- instead of building the design, returns:
+    - ``existence`` (boolean) -- instead of building the design, return:
 
         - ``True`` -- meaning that Sage knows how to build the design
 
@@ -238,7 +244,7 @@ def balanced_incomplete_block_design(v,k,existence=False,use_LJCR=False):
 
 def steiner_triple_system(n):
     r"""
-    Returns a Steiner Triple System
+    Return a Steiner Triple System
 
     A Steiner Triple System (STS) of a set `\{0,...,n-1\}`
     is a family `S` of 3-sets such that for any `i \not = j`
@@ -255,7 +261,7 @@ def steiner_triple_system(n):
 
     INPUT:
 
-    - ``n`` returns a Steiner Triple System of `\{0,...,n-1\}`
+    - ``n`` return a Steiner Triple System of `\{0,...,n-1\}`
 
     EXAMPLE:
 
@@ -323,13 +329,13 @@ def steiner_triple_system(n):
 
 def BIBD_from_TD(v,k,existence=False):
     r"""
-    Returns a BIBD through TD-based constructions.
+    Return a BIBD through TD-based constructions.
 
     INPUT:
 
     - ``v,k`` (integers) -- computes a `(v,k,1)`-BIBD.
 
-    - ``existence`` (boolean) -- instead of building the design, returns:
+    - ``existence`` (boolean) -- instead of building the design, return:
 
         - ``True`` -- meaning that Sage knows how to build the design
 
@@ -533,7 +539,7 @@ def BIBD_from_difference_family(G, D, check=True):
 
 def v_4_1_BIBD(v, check=True):
     r"""
-    Returns a `(v,4,1)`-BIBD.
+    Return a `(v,4,1)`-BIBD.
 
     A `(v,4,1)`-BIBD is an edge-decomposition of the complete graph `K_v` into
     copies of `K_4`. For more information, see
@@ -621,7 +627,7 @@ def v_4_1_BIBD(v, check=True):
 
 def BIBD_from_PBD(PBD,v,k,check=True,base_cases={}):
     r"""
-    Returns a `(v,k,1)`-BIBD from a `(r,K)`-PBD where `r=(v-1)/(k-1)`.
+    Return a `(v,k,1)`-BIBD from a `(r,K)`-PBD where `r=(v-1)/(k-1)`.
 
     This is Theorem 7.20 from [Stinson2004]_.
 
@@ -796,7 +802,7 @@ def _relabel_bibd(B,n,p=None):
 
 def PBD_4_5_8_9_12(v, check=True):
     """
-    Returns a `(v,\{4,5,8,9,12\})-`PBD on `v` elements.
+    Return a `(v,\{4,5,8,9,12\})`-PBD on `v` elements.
 
     A `(v,\{4,5,8,9,12\})`-PBD exists if and only if `v\equiv 0,1 \pmod 4`. The
     construction implemented here appears page 168 in [Stinson2004]_.
@@ -937,7 +943,7 @@ def _PBD_4_5_8_9_12_closure(B):
 
 def _get_t_u(v):
     r"""
-    Returns the parameters of table 7.1 from [Stinson2004]_.
+    Return the parameters of table 7.1 from [Stinson2004]_.
 
     INPUT:
 
@@ -967,7 +973,7 @@ def _get_t_u(v):
 
 def v_5_1_BIBD(v, check=True):
     r"""
-    Returns a `(v,5,1)`-BIBD.
+    Return a `(v,5,1)`-BIBD.
 
     This method follows the constuction from [ClaytonSmith]_.
 
@@ -1043,7 +1049,7 @@ def _get_r_s_t_u(v):
     r"""
     Implements the table from [ClaytonSmith]_
 
-    Returns the parameters ``r,s,t,u`` associated with an integer ``v``.
+    Return the parameters ``r,s,t,u`` associated with an integer ``v``.
 
     INPUT:
 
@@ -1075,7 +1081,7 @@ def _get_r_s_t_u(v):
 
 def PBD_from_TD(k,t,u):
     r"""
-    Returns a `(kt,\{k,t\})`-PBD if `u=0` and a `(kt+u,\{k,k+1,t,u\})`-PBD otherwise.
+    Return a `(kt,\{k,t\})`-PBD if `u=0` and a `(kt+u,\{k,k+1,t,u\})`-PBD otherwise.
 
     This is theorem 23 from [ClaytonSmith]_. The PBD is obtained from the blocks
     a truncated `TD(k+1,t)`, to which are added the blocks corresponding to the
@@ -1106,7 +1112,7 @@ def PBD_from_TD(k,t,u):
 
 def BIBD_5q_5_for_q_prime_power(q):
     r"""
-    Returns a `(5q,5,1)`-BIBD with `q\equiv 1\pmod 4` a prime power.
+    Return a `(5q,5,1)`-BIBD with `q\equiv 1\pmod 4` a prime power.
 
     See Theorem 24 [ClaytonSmith]_.
 

src/sage/combinat/designs/block_design.py

@@ -3,8 +3,7 @@
 
 A *block design* is a set together with a family of subsets (repeated subsets
 are allowed) whose members are chosen to satisfy some set of properties that are
-deemed useful for a particular application. See :wikipedia:`Block_design`. It is
-an object equivalent to an incidence structure.
+deemed useful for a particular application. See :wikipedia:`Block_design`.
 
 REFERENCES:
 
@@ -160,7 +159,7 @@ def are_hyperplanes_in_projective_geometry_parameters(v, k, lmbda, return_parame
 
 def ProjectiveGeometryDesign(n, d, F, algorithm=None, check=True):
     """
-    Returns a projective geometry design.
+    Return a projective geometry design.
 
     A projective geometry design of parameters `n,d,F` has for points the lines
     of `F^{n+1}`, and for blocks the `d+1`-dimensional subspaces of `F^{n+1}`,
@@ -221,7 +220,7 @@ def ProjectiveGeometryDesign(n, d, F, algorithm=None, check=True):
     if algorithm == "gap":   # Requires GAP's Design
         from sage.interfaces.gap import gap
         gap.load_package("design")
-        gap.eval("D := PGPointFlatBlockDesign( %s, %s, %d )"%(n,q,d))
+        gap.eval("D := PGPointFlatBlockDesign( %s, %s, %d )"%(n,F.order(),d))
         v = eval(gap.eval("D.v"))
         gblcks = eval(gap.eval("D.blocks"))
         gB = []
@@ -374,7 +373,7 @@ def projective_plane_to_OA(pplane, pt=None, check=True):
 
 def projective_plane(n, check=True, existence=False):
     r"""
-    Returns a projective plane of order ``n`` as a 2-design.
+    Return a projective plane of order ``n`` as a 2-design.
 
     A finite projective plane is a 2-design with `n^2+n+1` lines (or blocks) and
     `n^2+n+1` points. For more information on finite projective planes, see the
@@ -460,7 +459,7 @@ def projective_plane(n, check=True, existence=False):
 
 def AffineGeometryDesign(n, d, F):
     r"""
-    Returns an Affine Geometry Design.
+    Return an Affine Geometry Design.
 
     INPUT: