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.
EXAMPLE:
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
(list_of_entries, 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:
list_of_entries
– 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 whenlist_of_entries
is a list.sort
(boolean;True
) – whether to sort the list of methods lexicographically.only_local_functions
(boolean;True
) – iflist_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 assage.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.
EXAMPLE:
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: @ <BLANKLINE> :func:`~sage.graphs.generators.smallgraphs.PetersenGraph` @ The Petersen Graph is a named graph that consists of 10 vertices...
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: @ <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 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. <BLANKLINE> <BLANKLINE>
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` @ Returns the sparse6 representation of the graph as an ASCII string. ...
TESTS:
When the first sentence of the docstring spans over several lines:
sage: def a(): ....: r''' ....: Here is a very very very long sentence ....: that spans on several lines. ....: ....: EXAMP... ....: ''' ....: print("hey") sage: 'Here is a very very very long sentence that spans on several lines' in gen_rest_table_index([a]) True
The inherited methods do not show up:
sage: gen_rest_table_index(sage.combinat.posets.lattices.FiniteLatticePoset).count('\n') < 50 True sage: from sage.graphs.generic_graph import GenericGraph sage: A = gen_rest_table_index(Graph).count('\n') sage: B = gen_rest_table_index(GenericGraph).count('\n') sage: A < B True
When
only_local_functions
isFalse
, we do not includegen_rest_table_index
itself:sage: print(gen_rest_table_index(sage.misc.rest_index_of_methods, only_local_functions=True)) .. 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 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. <BLANKLINE> <BLANKLINE> sage: print(gen_rest_table_index(sage.misc.rest_index_of_methods, only_local_functions=False)) .. 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_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. <BLANKLINE> <BLANKLINE>
A function that is imported into a class under a different name is listed under its ‘new’ name:
sage: 'cliques_maximum' in gen_rest_table_index(Graph) True sage: 'all_max_cliques`' in gen_rest_table_index(Graph) False
-
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 decoratordoc_index()
does not work on a function.only_local_functions
(boolean;True
) – ifroot
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 assage.coding.codes_catalog
.
EXAMPLE:
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
) – ifroot
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 assage.coding.codes_catalog
.
OUTPUT:
A pair
(list,dict)
wherelist
is a list of function/methods anddict
associates to every function/method the name under which it appears inroot
.EXAMPLE:
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
TESTS:
A
staticmethod
is not callable. We must handle them correctly, however:sage: class A: ....: x = staticmethod(Graph.order) sage: list_of_subfunctions(A) ([<unbound method Graph.order>], {<unbound method Graph.order>: 'x'})