trac #18926: Auto-generated index of functions

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

@@ -293,6 +293,7 @@ Miscellaneous Inspection and Development Tools
    sage/misc/dev_tools
    sage/misc/function_mangling
    sage/misc/memory_info
+   sage/misc/rest_index_of_methods
 
 Low-Level Utilities
 -------------------

src/sage/combinat/designs/difference_family.py

@@ -9,19 +9,7 @@
 
 It defines the following functions:
 
-.. csv-table::
-    :class: contentstable
-    :widths: 30, 70
-    :delim: |
-
-    :func:`is_difference_family` | Check if the input is a (``k``, ``l``)-difference family.
-    :func:`difference_family` | Return a (``k``, ``l``)-difference family on an Abelian group of size ``v``.
-    :func:`radical_difference_family` | Return a radical difference family.
-    :func:`radical_difference_set` | Return a radical difference set.
-    :func:`singer_difference_set` | Return a difference set associated to hyperplanes in a projective space.
-    :func:`df_q_6_1` | Return a difference family with parameter `k=6` on a finite field.
-    :func:`one_radical_difference_family` | Return a radical difference family using an exhaustive search.
-    :func:`twin_prime_powers_difference_set` | Return a twin prime powers difference family.
+{INDEX_OF_FUNCTIONS}
 
 REFERENCES:
 
@@ -1338,3 +1326,7 @@ def difference_family(v, k, l=1, existence=False, explain_construction=False, ch
                 "Please contact sage-devel@googlegroups.com".format(G,v,k,l,D))
 
     return G, D
+
+from sage.misc.rest_index_of_methods import gen_rest_table_index
+import sys
+__doc__ = __doc__.format(INDEX_OF_FUNCTIONS=gen_rest_table_index(sys.modules[__name__]))

src/sage/combinat/designs/incidence_structures.py

@@ -4,35 +4,7 @@
 An incidence structure is specified by a list of points, blocks, or an incidence
 matrix ([1]_, [2]_). :class:`IncidenceStructure` instances have the following methods:
 
-.. csv-table::
-    :class: contentstable
-    :widths: 30, 70
-    :delim: |
-
-    :meth:`~IncidenceStructure.ground_set` | Return the ground set (i.e the list of points).
-    :meth:`~IncidenceStructure.num_points` | Return the size of the ground set.
-    :meth:`~IncidenceStructure.num_blocks` | Return the number of blocks.
-    :meth:`~IncidenceStructure.blocks` | Return the list of blocks.
-    :meth:`~IncidenceStructure.block_sizes` | Return the set of block sizes.
-    :meth:`~IncidenceStructure.degree` | Return the degree of a point `p`
-    :meth:`~IncidenceStructure.degrees` | Return the degree of all sets of given size, or the degree of all points.
-    :meth:`~IncidenceStructure.is_connected` | Test whether the design is connected.
-    :meth:`~IncidenceStructure.is_simple` | Test whether this design is simple (i.e. no repeated block).
-    :meth:`~IncidenceStructure.incidence_matrix` | Return the incidence matrix `A` of the design
-    :meth:`~IncidenceStructure.incidence_graph` | Return the incidence graph of the design
-    :meth:`~IncidenceStructure.packing` | Return a maximum packing
-    :meth:`~IncidenceStructure.relabel` | Relabel the ground set
-    :meth:`~IncidenceStructure.is_resolvable` | Test whether the hypergraph is resolvable
-    :meth:`~IncidenceStructure.is_t_design` | Test whether ``self`` is a `t-(v,k,l)` design.
-    :meth:`~IncidenceStructure.dual` | Return the dual design.
-    :meth:`~IncidenceStructure.automorphism_group` | Return the automorphism group
-    :meth:`~IncidenceStructure.canonical_label` | Return a canonical label for the incidence structure.
-    :meth:`~IncidenceStructure.is_isomorphic` | Return whether the two incidence structures are isomorphic.
-    :meth:`~IncidenceStructure.isomorphic_substructures_iterator` | Iterates over all copies of ``H2`` contained in ``self``
-    :meth:`~IncidenceStructure.edge_coloring` | Return an optimal edge coloring`
-    :meth:`~IncidenceStructure.copy` | Return a copy of the incidence structure.
-    :meth:`~IncidenceStructure.induced_substructure` | Return the substructure induced by a set of points.
-    :meth:`~IncidenceStructure.trace` | Return the trace of a set of point
+{METHODS_OF_IncidenceStructure}
 
 REFERENCES:
 
@@ -1939,3 +1911,6 @@ def _latex_(self):
 
         tex += "\\end{tikzpicture}"
         return tex
+
+from sage.misc.rest_index_of_methods import gen_rest_table_index
+__doc__ = __doc__.format(METHODS_OF_IncidenceStructure=gen_rest_table_index(IncidenceStructure))

src/sage/misc/rest_index_of_methods.py

@@ -0,0 +1,74 @@
+r"""
+ReST index of functions
+
+This module implemens a function that generates a ReST index of functions from a
+list of a class.
+
+{INDEX_OF_FUNCTIONS}
+
+"""
+
+def gen_rest_table_index(list_of_entries,sort=True):
+    r"""
+    Return a ReST table describing a list of functions.
+
+    INPUT:
+
+    - ``list_of_entries`` -- a list of functions, or a class. In the latter
+       case, all its methods are listed.
+
+    - ``sort`` (boolean; ``True``) -- whether to sort the list of methods
+      lexicographically.
+
+    EXAMPLE::
+
+        sage: from sage.misc.rest_index_of_methods import gen_rest_table_index
+        sage: gen_rest_table_index([graphs.PetersenGraph])
+        .. csv-table::
+           :class: contentstable
+           :widths: 30, 70
+           :delim: |
+        ...
+           :func:`~sage.graphs.generators.smallgraphs.PetersenGraph` | The Petersen Graph is a named graph that consists of 10 vertices
+        ...
+    """
+    import inspect
+
+    # If input is a class/module, we list all its non-private and methods/functions
+    if (inspect.isclass(list_of_entries) or
+        inspect.ismodule(list_of_entries)):
+        root = list_of_entries
+        list_of_entries = [getattr(root,name) for name,f in root.__dict__.items() if
+                           (not name.startswith('_')     and # private functions
+                            not hasattr(f,'trac_number') and # deprecated functions
+                            not inspect.isclass(f)       and # classes
+                            inspect.getmodule(root) == inspect.getmodule(f))] # not imported from elsewhere
+
+    assert isinstance(list_of_entries,list)
+
+    s = (".. csv-table::\n"
+         "   :class: contentstable\n"
+         "   :widths: 30, 70\n"
+         "   :delim: |\n\n")
+
+    if sort:
+        list_of_entries.sort(key=lambda x:getattr(x,'__name__',''))
+
+    for e in list_of_entries:
+
+        if inspect.ismethod(e):
+            link = ":meth:`~"+str(e.im_class.__module__)+"."+str(e.im_class.__name__)+"."+e.__name__+"`"
+        elif inspect.isfunction(e):
+            link = ":func:`~"+str(e.__module__)+"."+str(e.__name__)+"`"
+        else:
+            continue
+
+        # Descriptions of the method/function
+        desc = e.__doc__.splitlines()
+        desc = desc[0] if desc[0] else desc[1]
+
+        s += "   {} | {}\n".format(link,desc.lstrip())
+
+    return s+'\n'
+
+__doc__ = __doc__.format(INDEX_OF_FUNCTIONS=gen_rest_table_index([gen_rest_table_index]))