ReST index of functions#

This module contains a function that generates a ReST index table of functions for use in doc-strings.

gen_rest_table_index()

Return a ReST table describing a list of functions.

gen_thematic_rest_table_index()

Return a ReST string of thematically sorted functions (or methods) of a module (or class).

sage.misc.rest_index_of_methods.doc_index(name)#

Attribute an index name to a function.

This decorator can be applied to a function/method in order to specify in which index it must appear, in the index generated by gen_thematic_rest_table_index().

INPUT:

  • name – a string, which will become the title of the index in which this function/method will appear.

EXAMPLES:

sage: from sage.misc.rest_index_of_methods import doc_index
sage: @doc_index("Wouhouuuuu")
....: def a():
....:     print("Hey")
sage: a.doc_index
'Wouhouuuuu'
sage.misc.rest_index_of_methods.gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, root=None)#

Return a ReST table describing a list of functions.

The list of functions can either be given explicitly, or implicitly as the functions/methods of a module or class.

In the case of a class, only non-inherited methods are listed.

INPUT:

  • obj – a list of functions, a module or a class. If given a list of functions, the generated table will consist of these. If given a module or a class, all functions/methods it defines will be listed, except deprecated or those starting with an underscore. In the case of a class, note that inherited methods are not displayed.

  • names – a dictionary associating a name to a function. Takes precedence over the automatically computed name for the functions. Only used when list_of_entries is a list.

  • sort – boolean (default: True); whether to sort the list of methods lexicographically.

  • only_local_functions – boolean (default: True); if list_of_entries is a module, only_local_functions = True means that imported functions will be filtered out. This can be useful to disable for making indexes of e.g. catalog modules such as sage.coding.codes_catalog.

  • root – module or class (default: None); the module, or class, whose elements are to be listed. This is needed to recover the class when this method is called from gen_thematic_rest_table_index() (see github issue #36178).

Warning

The ReST tables returned by this function use ‘@’ as a delimiter for cells. This can cause trouble if the first sentence in the documentation of a function contains the ‘@’ character.

EXAMPLES:

sage: from sage.misc.rest_index_of_methods import gen_rest_table_index
sage: print(gen_rest_table_index([graphs.PetersenGraph]))                       # needs sage.graphs
.. csv-table::
   :class: contentstable
   :widths: 30, 70
   :delim: @

   :func:`~sage.graphs.generators.smallgraphs.PetersenGraph` @ Return the Petersen Graph.

The table of a module:

sage: print(gen_rest_table_index(sage.misc.rest_index_of_methods))
.. csv-table::
   :class: contentstable
   :widths: 30, 70
   :delim: @

   :func:`~sage.misc.rest_index_of_methods.doc_index` @ Attribute an index name to a function.
   :func:`~sage.misc.rest_index_of_methods.gen_rest_table_index` @ Return a ReST table describing a list of functions.
   :func:`~sage.misc.rest_index_of_methods.gen_thematic_rest_table_index` @ Return a ReST string of thematically sorted functions (or methods) of a module (or class).
   :func:`~sage.misc.rest_index_of_methods.list_of_subfunctions` @ Return the functions (resp. methods) of a given module (resp. class) with their names.

The table of a class:

sage: print(gen_rest_table_index(Graph))                                        # needs sage.graphs
.. csv-table::
   :class: contentstable
   :widths: 30, 70
   :delim: @
...
   :meth:`~sage.graphs.graph.Graph.sparse6_string` @ Return the sparse6 representation of the graph as an ASCII string.
...
sage.misc.rest_index_of_methods.gen_thematic_rest_table_index(root, additional_categories=None, only_local_functions=True)#

Return a ReST string of thematically sorted functions (or methods) of a module (or class).

INPUT:

  • root – the module, or class, whose elements are to be listed.

  • additional_categories – dictionary (default: None); a dictionary associating a category (given as a string) to a function’s name. Can be used when the decorator doc_index() does not work on a function.

  • only_local_functions – boolean (default: True); if root is a module, only_local_functions = True means that imported functions will be filtered out. This can be useful to disable for making indexes of e.g. catalog modules such as sage.coding.codes_catalog.

EXAMPLES:

sage: from sage.misc.rest_index_of_methods import gen_thematic_rest_table_index, list_of_subfunctions
sage: l = list_of_subfunctions(Graph)[0]                                        # needs sage.graphs
sage: Graph.bipartite_color in l                                                # needs sage.graphs
True
sage.misc.rest_index_of_methods.list_of_subfunctions(root, only_local_functions=True)#

Return the functions (resp. methods) of a given module (resp. class) with their names.

INPUT:

  • root – the module, or class, whose elements are to be listed.

  • only_local_functions – boolean (default: True); if root is a module, only_local_functions = True means that imported functions will be filtered out. This can be useful to disable for making indexes of e.g. catalog modules such as sage.coding.codes_catalog.

OUTPUT:

A pair (list,dict) where list is a list of function/methods and dict associates to every function/method the name under which it appears in root.

EXAMPLES:

sage: from sage.misc.rest_index_of_methods import list_of_subfunctions
sage: l = list_of_subfunctions(Graph)[0]                                        # needs sage.graphs
sage: Graph.bipartite_color in l                                                # needs sage.graphs
True