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)[source]#

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

sage: from sage.misc.rest_index_of_methods import doc_index
sage: @doc_index("Wouhouuuuu")
....: def a():
....:     print("Hey")
sage: a.doc_index
'Wouhouuuuu'

Python

>>> from sage.all import *
>>> from sage.misc.rest_index_of_methods import doc_index
>>> @doc_index("Wouhouuuuu")
... def a():
...     print("Hey")
>>> 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)[source]#

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 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

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.

Python

>>> from sage.all import *
>>> from sage.misc.rest_index_of_methods import gen_rest_table_index
>>> print(gen_rest_table_index([graphs.PetersenGraph]))                       # needs sage.graphs
.. csv-table::
   :class: contentstable
   :widths: 30, 70
   :delim: @
<BLANKLINE>
   :func:`~sage.graphs.generators.smallgraphs.PetersenGraph` @ Return the Petersen Graph.

The table of a module:

Sage

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.

Python

>>> from sage.all import *
>>> print(gen_rest_table_index(sage.misc.rest_index_of_methods))
.. csv-table::
   :class: contentstable
   :widths: 30, 70
   :delim: @
<BLANKLINE>
   :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.
<BLANKLINE>
<BLANKLINE>

The table of a class:

Sage

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.
...

Python

>>> from sage.all import *
>>> 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)[source]#

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

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

Python

>>> from sage.all import *
>>> from sage.misc.rest_index_of_methods import gen_thematic_rest_table_index, list_of_subfunctions
>>> l = list_of_subfunctions(Graph)[Integer(0)]                                        # needs sage.graphs
>>> Graph.bipartite_color in l                                                # needs sage.graphs
True

sage.misc.rest_index_of_methods.list_of_subfunctions(root, only_local_functions=True)[source]#

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

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

Python

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