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

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; True) – whether to sort the list of methods lexicographically.

  • only_local_functions (boolean; 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.

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]))
.. 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 function (or methods) of a module (or class).
   :func:`~sage.misc.rest_index_of_methods.list_of_subfunctions` @ Returns 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))
.. 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 function (or methods) of a module (or class).

INPUT:

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

  • additional_categories – 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; 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]
sage: Graph.bipartite_color in l
True
sage.misc.rest_index_of_methods.list_of_subfunctions(root, only_local_functions=True)

Returns 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; 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]
sage: Graph.bipartite_color in l
True