ReST index of functions - Utilities

Skip to content
Back to top
View this page
Edit this page

# 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` – 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)

  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` – 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` – 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)

  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)

  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