From 1f5758365664538a1d8ffc4516887061121b817d Mon Sep 17 00:00:00 2001 From: dcoudert Date: Sat, 2 Sep 2023 18:14:49 +0200 Subject: [PATCH 1/6] fix issue #36178 --- src/sage/misc/rest_index_of_methods.py | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/src/sage/misc/rest_index_of_methods.py b/src/sage/misc/rest_index_of_methods.py index 82b988deda2..17bad8336d8 100644 --- a/src/sage/misc/rest_index_of_methods.py +++ b/src/sage/misc/rest_index_of_methods.py @@ -14,7 +14,7 @@ from sage.misc.sageinspect import is_function_or_cython_function as _isfunction -def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True): +def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, root=None): r""" Return a ReST table describing a list of functions. @@ -43,6 +43,10 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True): will be filtered out. This can be useful to disable for making indexes of e.g. catalog modules such as :mod:`sage.coding.codes_catalog`. + - ``root`` -- (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 :meth:`gen_thematic_rest_table_index`. + .. WARNING:: The ReST tables returned by this function use '@' as a delimiter for @@ -169,14 +173,24 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True): if sort: list_of_entries.sort(key=fname) + obj_or_root_is_class = False + if inspect.isclass(root): + obj_or_root_is_class = True + class_name = root.__name__ + module_name = root.__module__ + elif inspect.isclass(obj): + obj_or_root_is_class = True + class_name = obj.__name__ + module_name = obj.__module__ + for e in list_of_entries: if inspect.ismethod(e): link = ":meth:`~{module}.{cls}.{func}`".format( module=e.im_class.__module__, cls=e.im_class.__name__, func=fname(e)) - elif _isfunction(e) and inspect.isclass(obj): + elif _isfunction(e) and obj_or_root_is_class: link = ":meth:`~{module}.{cls}.{func}`".format( - module=obj.__module__, cls=obj.__name__, func=fname(e)) + module=module_name, cls=class_name, func=fname(e)) elif _isfunction(e): link = ":func:`~{module}.{func}`".format( module=e.__module__, func=fname(e)) @@ -317,7 +331,7 @@ def gen_thematic_rest_table_index(root,additional_categories=None,only_local_fun except AttributeError: doc_ind = "Unsorted" theme_to_function[doc_ind].append(f) - s = ["**"+theme+"**\n\n"+gen_rest_table_index(list_of_functions,names=names) + s = ["**" + theme + "**\n\n" + gen_rest_table_index(list_of_functions, names=names, root=root) for theme, list_of_functions in sorted(theme_to_function.items())] return "\n\n".join(s) From 6c975ab3999ea26ea31a709d3f529d9f94f2be10 Mon Sep 17 00:00:00 2001 From: dcoudert Date: Sat, 2 Sep 2023 18:20:35 +0200 Subject: [PATCH 2/6] fix some links in sage/graphs/isgci.py --- src/sage/graphs/isgci.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/sage/graphs/isgci.py b/src/sage/graphs/isgci.py index 147e2ba2778..2ec23b13afa 100644 --- a/src/sage/graphs/isgci.py +++ b/src/sage/graphs/isgci.py @@ -135,28 +135,28 @@ * - Apex - - :meth:`~Graph.is_apex()`, - :meth:`~Graph.apex_vertices()` + - :meth:`~sage.graphs.graph.Graph.is_apex()`, + :meth:`~sage.graphs.graph.Graph.apex_vertices()` * - AT_free - - :meth:`~Graph.is_asteroidal_triple_free` + - :meth:`~sage.graphs.graph.Graph.is_asteroidal_triple_free` * - Biconnected - - :meth:`~Graph.is_biconnected`, - :meth:`~GenericGraph.blocks_and_cut_vertices`, - :meth:`~GenericGraph.blocks_and_cuts_tree` + - :meth:`~sage.graphs.graph.Graph.is_biconnected`, + :meth:`~sage.graphs.generic_graph.GenericGraph.blocks_and_cut_vertices`, + :meth:`~sage.graphs.generic_graph.GenericGraph.blocks_and_cuts_tree` * - BinaryTrees - :meth:`~sage.graphs.graph_generators.GraphGenerators.BalancedTree`, - :meth:`~Graph.is_tree` + :meth:`~sage.graphs.graph.Graph.is_tree` * - Bipartite - :meth:`~sage.graphs.graph_generators.GraphGenerators.BalancedTree`, - :meth:`~sage.graphs.graph.Graph.is_bipartite` + :meth:`~sage.graphs.generic_graph.GenericGraph.is_bipartite` * - Block @@ -212,7 +212,7 @@ * - Polyhedral - - :meth:`~sage.graphs.generic_graph.Graph.is_polyhedral` + - :meth:`~sage.graphs.graph.Graph.is_polyhedral` * - Split From 42be2e6a812a310789962fc39564954a475f3be2 Mon Sep 17 00:00:00 2001 From: dcoudert Date: Sat, 2 Sep 2023 18:40:10 +0200 Subject: [PATCH 3/6] add doctest in sage/misc/rest_index_of_methods.py --- src/sage/misc/rest_index_of_methods.py | 60 +++++++++++++++----------- 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/src/sage/misc/rest_index_of_methods.py b/src/sage/misc/rest_index_of_methods.py index 17bad8336d8..f425b9bdcf9 100644 --- a/src/sage/misc/rest_index_of_methods.py +++ b/src/sage/misc/rest_index_of_methods.py @@ -35,17 +35,19 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, 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. + - ``sort`` -- boolean (default: ``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 :mod:`sage.coding.codes_catalog`. + - ``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 + :mod:`sage.coding.codes_catalog`. - - ``root`` -- (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 :meth:`gen_thematic_rest_table_index`. + - ``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 :meth:`gen_thematic_rest_table_index` (see + :trac:`36178`). .. WARNING:: @@ -75,7 +77,7 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, :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. + :func:`~sage.misc.rest_index_of_methods.list_of_subfunctions` @ Return the functions (resp. methods) of a given module (resp. class) with their names. @@ -128,7 +130,7 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, :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. + :func:`~sage.misc.rest_index_of_methods.list_of_subfunctions` @ Return the functions (resp. methods) of a given module (resp. class) with their names. sage: print(gen_rest_table_index(sage.misc.rest_index_of_methods, only_local_functions=False)) @@ -139,7 +141,7 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, :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. + :func:`~sage.misc.rest_index_of_methods.list_of_subfunctions` @ Return the functions (resp. methods) of a given module (resp. class) with their names. @@ -150,6 +152,13 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, True sage: 'all_max_cliques`' in gen_rest_table_index(Graph) # needs sage.graphs False + + Check that :trac:`36178` is fixed:: + + sage: print(gen_rest_table_index(Graph)) # needs sage.graphs + ... + :meth:`~sage.graphs.graph.Graph.independent_set` @ Return a maximum independent set. + ... """ if names is None: names = {} @@ -218,15 +227,15 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, def list_of_subfunctions(root, only_local_functions=True): r""" - Returns the functions (resp. methods) of a given module (resp. class) with their names. + 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; ``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 + - ``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 :mod:`sage.coding.codes_catalog`. OUTPUT: @@ -290,21 +299,22 @@ def can_import(f): return list(functions.keys()), functions -def gen_thematic_rest_table_index(root,additional_categories=None,only_local_functions=True): +def gen_thematic_rest_table_index(root, additional_categories=None, only_local_functions=True): r""" - Return a ReST string of thematically sorted function (or methods) of a module (or class). + 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 - :func:`doc_index` does not work on a function. + - ``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 :func:`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 + - ``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 :mod:`sage.coding.codes_catalog`. EXAMPLES:: @@ -359,7 +369,7 @@ def doc_index(name): 'Wouhouuuuu' """ def hey(f): - setattr(f,"doc_index",name) + setattr(f, "doc_index", name) return f return hey From 71a55d9edfc840c307f5fc61ce7982a0d52352f5 Mon Sep 17 00:00:00 2001 From: dcoudert Date: Sat, 2 Sep 2023 18:41:14 +0200 Subject: [PATCH 4/6] remove a useless link in sage/graphs.digraph.py --- src/sage/graphs/digraph.py | 1 - 1 file changed, 1 deletion(-) diff --git a/src/sage/graphs/digraph.py b/src/sage/graphs/digraph.py index a8e6e9997b1..d30d5e63efa 100644 --- a/src/sage/graphs/digraph.py +++ b/src/sage/graphs/digraph.py @@ -84,7 +84,6 @@ :meth:`~DiGraph.strongly_connected_components_subgraphs` | Return the strongly connected components as a list of subgraphs. :meth:`~DiGraph.strongly_connected_component_containing_vertex` | Return the strongly connected component containing a given vertex :meth:`~DiGraph.strongly_connected_components` | Return the list of strongly connected components. - :meth:`~DiGraph.immediate_dominators` | Return the immediate dominators of all vertices reachable from `root`. :meth:`~DiGraph.strong_articulation_points` | Return the strong articulation points of this digraph. From f34a9b35f31e39a7794ddfc65eb906c7bc43987c Mon Sep 17 00:00:00 2001 From: dcoudert Date: Sat, 2 Sep 2023 18:45:48 +0200 Subject: [PATCH 5/6] fix some links in sage/graphs/generators/chessboard.py --- src/sage/graphs/generators/chessboard.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/sage/graphs/generators/chessboard.py b/src/sage/graphs/generators/chessboard.py index 59517d128bb..dfe5b15b273 100644 --- a/src/sage/graphs/generators/chessboard.py +++ b/src/sage/graphs/generators/chessboard.py @@ -4,11 +4,11 @@ The methods defined here appear in :mod:`sage.graphs.graph_generators`. -- :meth:`BishopGraph ` -- :meth:`KingGraph ` -- :meth:`KnightGraph ` -- :meth:`QueenGraph ` -- :meth:`RookGraph ` +- :meth:`BishopGraph ` +- :meth:`KingGraph ` +- :meth:`KnightGraph ` +- :meth:`QueenGraph ` +- :meth:`RookGraph ` AUTHORS: From a48893b451ba5c40b65bb38349dfb12aaed5cb7f Mon Sep 17 00:00:00 2001 From: dcoudert Date: Sun, 3 Sep 2023 09:44:22 +0200 Subject: [PATCH 6/6] review comments --- src/sage/graphs/isgci.py | 4 ++-- src/sage/misc/rest_index_of_methods.py | 15 ++++++++------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/src/sage/graphs/isgci.py b/src/sage/graphs/isgci.py index 2ec23b13afa..e19c4a8103e 100644 --- a/src/sage/graphs/isgci.py +++ b/src/sage/graphs/isgci.py @@ -135,8 +135,8 @@ * - Apex - - :meth:`~sage.graphs.graph.Graph.is_apex()`, - :meth:`~sage.graphs.graph.Graph.apex_vertices()` + - :meth:`~sage.graphs.graph.Graph.is_apex`, + :meth:`~sage.graphs.graph.Graph.apex_vertices` * - AT_free diff --git a/src/sage/misc/rest_index_of_methods.py b/src/sage/misc/rest_index_of_methods.py index f425b9bdcf9..d1b102829c9 100644 --- a/src/sage/misc/rest_index_of_methods.py +++ b/src/sage/misc/rest_index_of_methods.py @@ -47,7 +47,7 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, - ``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 :meth:`gen_thematic_rest_table_index` (see - :trac:`36178`). + :issue:`36178`). .. WARNING:: @@ -76,7 +76,7 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, :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.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. @@ -129,7 +129,7 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, :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.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. @@ -140,7 +140,7 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, :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_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.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. @@ -153,7 +153,7 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, sage: 'all_max_cliques`' in gen_rest_table_index(Graph) # needs sage.graphs False - Check that :trac:`36178` is fixed:: + Check that :issue:`36178` is fixed:: sage: print(gen_rest_table_index(Graph)) # needs sage.graphs ... @@ -301,7 +301,7 @@ def can_import(f): def gen_thematic_rest_table_index(root, additional_categories=None, only_local_functions=True): r""" - Return a ReST string of thematically sorted function (or methods) of a + Return a ReST string of thematically sorted functions (or methods) of a module (or class). INPUT: @@ -374,4 +374,5 @@ def hey(f): return hey -__doc__ = __doc__.format(INDEX_OF_FUNCTIONS=gen_rest_table_index([gen_rest_table_index])) +__doc__ = __doc__.format(INDEX_OF_FUNCTIONS=gen_rest_table_index([gen_rest_table_index, + gen_thematic_rest_table_index]))