gh-36179: Improve methods in sage.misc.rest_index_of_methods to fix…

… the documentation of graphs.

    
Fixes #36178.

We ensure that method
`sage.misc.rest_index_of_methods.gen_thematic_rest_table_index` adds the
correct links to methods in the thematic tables of the documentation.
For instance, some links were missing in the thematic tables of https://
doc.sagemath.org/html/en/reference/graphs/sage/graphs/graph.html.

We also fix some links in the documentation.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #36179
Reported by: David Coudert
Reviewer(s): David Coudert, Frédéric Chapoton

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.
 
 

src/sage/graphs/generators/chessboard.py

@@ -4,11 +4,11 @@
 
 The methods defined here appear in :mod:`sage.graphs.graph_generators`.
 
-- :meth:`BishopGraph <GraphGenerators.BishopGraph>`
-- :meth:`KingGraph <GraphGenerators.KingGraph>`
-- :meth:`KnightGraph <GraphGenerators.KnightGraph>`
-- :meth:`QueenGraph <GraphGenerators.QueenGraph>`
-- :meth:`RookGraph <GraphGenerators.RookGraph>`
+- :meth:`BishopGraph <sage.graphs.graph_generators.GraphGenerators.BishopGraph>`
+- :meth:`KingGraph <sage.graphs.graph_generators.GraphGenerators.KingGraph>`
+- :meth:`KnightGraph <sage.graphs.graph_generators.GraphGenerators.KnightGraph>`
+- :meth:`QueenGraph <sage.graphs.graph_generators.GraphGenerators.QueenGraph>`
+- :meth:`RookGraph <sage.graphs.graph_generators.GraphGenerators.RookGraph>`
 
 AUTHORS:
 

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
 

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.
 
@@ -35,13 +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`` -- 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
+      :issue:`36178`).
 
     .. WARNING::
 
@@ -70,8 +76,8 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True):
         <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.
+           :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>
 
@@ -123,8 +129,8 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True):
         <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.
+           :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>
         sage: print(gen_rest_table_index(sage.misc.rest_index_of_methods, only_local_functions=False))
@@ -134,8 +140,8 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True):
            :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.
+           :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>
 
@@ -146,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 :issue:`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 = {}
@@ -169,14 +182,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))
@@ -204,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:
@@ -276,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 functions (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::
@@ -317,7 +341,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)
 
@@ -345,9 +369,10 @@ def doc_index(name):
         'Wouhouuuuu'
     """
     def hey(f):
-        setattr(f,"doc_index",name)
+        setattr(f, "doc_index", name)
         return 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]))