Major rework in documentation (#346)

This PR changes the documentation by: * Organizing algorithms by theme instead of splitting them into universal and type specific * Creating two new sections for type specific algorithms in the docs * Functions that have no graph_* or digraph_* equivalents are listed under Algorithms section instead of the type Advanced API section; no function is listed twice Step towards #328 * Major rework in documentation * Address PR comments * Remove duplicate Converters section from rebase * Fix doc lint Co-authored-by: Matthew Treinish <[email protected]>
Qiskit · May 31, 2021 · 30c1115 · 30c1115
1 parent ab1f984
commit 30c1115
Show file tree

Hide file tree

Showing 4 changed files with 185 additions and 105 deletions.
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -14,6 +14,122 @@ Graph Classes
     retworkx.PyDiGraph
     retworkx.PyDAG
 
+Algorithm Functions
+===================
+
+.. _shortest-paths:
+
+Shortest Paths
+--------------
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.dijkstra_shortest_paths
+   retworkx.dijkstra_shortest_path_lengths
+   retworkx.all_pairs_dijkstra_shortest_paths
+   retworkx.all_pairs_dijkstra_path_lengths
+   retworkx.distance_matrix
+   retworkx.floyd_warshall_numpy
+   retworkx.floyd_warshall
+   retworkx.astar_shortest_path
+   retworkx.k_shortest_path_lengths
+
+.. _traversal:
+
+Traversal
+---------
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.dfs_edges
+   retworkx.bfs_successors
+   retworkx.topological_sort
+   retworkx.lexicographical_topological_sort
+   retworkx.descendants
+   retworkx.ancestors
+   retworkx.collect_runs
+
+.. _dag-algorithms:
+
+DAG Algorithms
+--------------
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.dag_longest_path
+   retworkx.dag_longest_path_length
+   retworkx.is_directed_acyclic_graph
+   retworkx.layers
+
+.. _tree:
+
+Tree
+----
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.minimum_spanning_edges
+   retworkx.minimum_spanning_tree
+
+.. _isomorphism:
+
+Isomorphism
+-----------
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.is_isomorphic
+   retworkx.is_subgraph_isomorphic
+   retworkx.is_isomorphic_node_match
+
+.. _matching:
+
+Matching
+--------
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.max_weight_matching
+   retworkx.is_matching
+   retworkx.is_maximal_matching
+
+.. _connectivity-cycle-finding:
+
+Connectivity and Cycles
+-----------------------
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.strongly_connected_components
+   retworkx.number_weakly_connected_components
+   retworkx.weakly_connected_components
+   retworkx.is_weakly_connected
+   retworkx.cycle_basis
+   retworkx.digraph_find_cycle
+
+.. _other-algorithms:
+
+Other Algorithm Functions
+-------------------------
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.complement
+   retworkx.adjacency_matrix
+   retworkx.all_simple_paths
+   retworkx.transitivity
+   retworkx.core_number
+   retworkx.graph_greedy_color
+   retworkx.digraph_union
+
 Generators
 ==========
 
@@ -46,141 +162,105 @@ Random Circuit Functions
     retworkx.undirected_gnm_random_graph
     retworkx.random_geometric_graph
 
-Algorithm Functions
-===================
+.. _layout-functions:
 
-Specific Graph Type Methods
----------------------------
+Layout Functions
+================
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.random_layout
+   retworkx.spring_layout
+   retworkx.bipartite_layout
+   retworkx.circular_layout
+   retworkx.shell_layout
+   retworkx.spiral_layout
+
+
+.. _converters:
+
+Converters
+==========
+
+.. autosummary::
+   :toctree: stubs
+
+   retworkx.networkx_converter
+
+.. _api-functions-pydigraph:
+
+API functions for PyDigraph
+===========================
+
+These functions are algorithm functions that are type specific for
+:class:`~retworkx.PyDiGraph` or :class:`~retworkx.PyDAG` objects. Universal
+functions from Retworkx API that work for both graph types internally call
+the functions from the explicitly typed based on the data type.
 
 .. autosummary::
    :toctree: stubs
 
-   retworkx.bfs_successors
-   retworkx.dag_longest_path
-   retworkx.dag_longest_path_length
-   retworkx.number_weakly_connected_components
-   retworkx.weakly_connected_components
-   retworkx.is_weakly_connected
-   retworkx.is_directed_acyclic_graph
    retworkx.digraph_is_isomorphic
-   retworkx.graph_is_isomorphic
    retworkx.digraph_is_subgraph_isomorphic
-   retworkx.graph_is_subgraph_isomorphic
-   retworkx.topological_sort
-   retworkx.descendants
-   retworkx.ancestors
-   retworkx.lexicographical_topological_sort
-   retworkx.graph_distance_matrix
    retworkx.digraph_distance_matrix
-   retworkx.floyd_warshall
-   retworkx.graph_floyd_warshall_numpy
    retworkx.digraph_floyd_warshall_numpy
-   retworkx.collect_runs
-   retworkx.layers
    retworkx.digraph_adjacency_matrix
-   retworkx.graph_adjacency_matrix
-   retworkx.graph_all_simple_paths
    retworkx.digraph_all_simple_paths
-   retworkx.graph_astar_shortest_path
    retworkx.digraph_astar_shortest_path
-   retworkx.graph_dijkstra_shortest_paths
    retworkx.digraph_dijkstra_shortest_paths
    retworkx.digraph_all_pairs_dijkstra_shortest_paths
-   retworkx.graph_dijkstra_shortest_path_lengths
-   retworkx.graph_all_pairs_dijkstra_shortest_paths
    retworkx.digraph_dijkstra_shortest_path_lengths
    retworkx.digraph_all_pairs_dijkstra_path_lengths
-   retworkx.graph_k_shortest_path_lengths
-   retworkx.graph_all_pairs_dijkstra_path_lengths
    retworkx.digraph_k_shortest_path_lengths
-   retworkx.graph_greedy_color
-   retworkx.cycle_basis
-   retworkx.strongly_connected_components
-   retworkx.graph_dfs_edges
    retworkx.digraph_dfs_edges
    retworkx.digraph_find_cycle
-   retworkx.digraph_union
-   retworkx.is_matching
-   retworkx.is_maximal_matching
-   retworkx.max_weight_matching
-   retworkx.minimum_spanning_edges
-   retworkx.minimum_spanning_tree
-   retworkx.graph_transitivity
    retworkx.digraph_transitivity
-   retworkx.graph_core_number
    retworkx.digraph_core_number
-   retworkx.graph_complement
    retworkx.digraph_complement
+   retworkx.digraph_random_layout
+   retworkx.digraph_bipartite_layout
+   retworkx.digraph_circular_layout
+   retworkx.digraph_shell_layout
+   retworkx.digraph_spiral_layout
+   retworkx.digraph_spring_layout
 
-.. _universal-functions:
-
-Universal Functions
--------------------
-
-These functions are algorithm functions that wrap per graph object
-type functions in the algorithms API but can be run with a
-:class:`~retworkx.PyGraph`, :class:`~retworkx.PyDiGraph`, or
-:class:`~retworkx.PyDAG` object.
-
-.. autosummary::
-   :toctree: stubs
 
-   retworkx.complement
-   retworkx.distance_matrix
-   retworkx.floyd_warshall_numpy
-   retworkx.adjacency_matrix
-   retworkx.all_simple_paths
-   retworkx.astar_shortest_path
-   retworkx.dijkstra_shortest_paths
-   retworkx.dijkstra_shortest_path_lengths
-   retworkx.all_pairs_dijkstra_shortest_paths
-   retworkx.all_pairs_dijkstra_path_lengths
-   retworkx.k_shortest_path_lengths
-   retworkx.dfs_edges
-   retworkx.is_isomorphic
-   retworkx.is_subgraph_isomorphic
-   retworkx.is_isomorphic_node_match
-   retworkx.transitivity
-   retworkx.core_number
-   retworkx.random_layout
-   retworkx.bipartite_layout
-   retworkx.circular_layout
-   retworkx.shell_layout
-   retworkx.spiral_layout
-   retworkx.spring_layout
+.. _api-functions-pygraph:
 
-.. _layout-functions:
+API functions for PyGraph
+=========================
 
-Layout Functions
-================
+These functions are algorithm functions that are type specific for
+:class:`~retworkx.PyGraph` objects. Universal functions from Retworkx API that
+work for both graph types internally call the functions from the explicitly
+typed API based on the data type.
 
 .. autosummary::
    :toctree: stubs
 
-   retworkx.random_layout
-   retworkx.spring_layout
+   retworkx.graph_is_isomorphic
+   retworkx.graph_is_subgraph_isomorphic
+   retworkx.graph_distance_matrix
+   retworkx.graph_floyd_warshall_numpy
+   retworkx.graph_adjacency_matrix
+   retworkx.graph_all_simple_paths
+   retworkx.graph_astar_shortest_path
+   retworkx.graph_dijkstra_shortest_paths
+   retworkx.graph_dijkstra_shortest_path_lengths
+   retworkx.graph_all_pairs_dijkstra_shortest_paths
+   retworkx.graph_k_shortest_path_lengths
+   retworkx.graph_all_pairs_dijkstra_path_lengths
+   retworkx.graph_dfs_edges
+   retworkx.graph_transitivity
+   retworkx.graph_core_number
+   retworkx.graph_complement
    retworkx.graph_random_layout
-   retworkx.digraph_random_layout
-   retworkx.bipartite_layout
    retworkx.graph_bipartite_layout
-   retworkx.digraph_bipartite_layout
-   retworkx.circular_layout
    retworkx.graph_circular_layout
-   retworkx.digraph_circular_layout
-   retworkx.shell_layout
    retworkx.graph_shell_layout
-   retworkx.digraph_shell_layout
-   retworkx.spiral_layout
    retworkx.graph_spiral_layout
-   retworkx.digraph_spiral_layout
-
-Converters
-----------
-
-.. autosummary::
-   :toctree: stubs
-
-   retworkx.networkx_converter
+   retworkx.graph_spring_layout
 
 Exceptions
 ==========

diff --git a/docs/source/networkx.rst b/docs/source/networkx.rst
@@ -89,11 +89,11 @@ or more concisely::
     dist_matrix = rx.digraph_floyd_warshall_numpy(graph,
                                                   weight_fn=lambda edge: edge)
 
-The other large difference to keep in mind is that most functions in retworkx
+The other large difference to keep in mind is that many functions in retworkx
 are explicitly typed. This means that they either always return or accept
 either a :class:`~retworkx.PyDiGraph` or a :class:`~retworkx.PyGraph` but not
-both. The exception to this are the :ref:`universal-functions` which will
-dispatch to the statically typed equivalent based on the object they receive.
+both. Generally, functions prefixed with `graph_*` and `digraph_*` explicitly typed.
+Explicitly typed functions also indicate their type on the docstrings.
 This is different from networkx where everything is pretty much dynamically
 typed and you can pass a graph object to any function and it will work as
 expected (unless it isn't supported and then it will raise an exception).

diff --git a/releasenotes/notes/0.8.0/add-universal-functions-1e54351f1f7afa4b.yaml b/releasenotes/notes/0.8.0/add-universal-functions-1e54351f1f7afa4b.yaml
@@ -1,7 +1,7 @@
 ---
 features:
   - |
-    New :ref:`universal-functions` that can take in a :class:`~retworkx.PyGraph`
+    New universal functions that can take in a :class:`~retworkx.PyGraph`
     or :class:`~retworkx.PyDiGraph` instead of being class specific have been
     to the retworkx API. These new functions are:
 

diff --git a/releasenotes/notes/0.8.0/prepare-0.8-f3ec8cbf07dfdbb7.yaml b/releasenotes/notes/0.8.0/prepare-0.8-f3ec8cbf07dfdbb7.yaml
@@ -3,7 +3,7 @@ prelude: >
     This release includes several new features and bug fixes. The main features
     for this release are some usability improvements including the introduction
     of new methods for interacting with edges, constructing graphs from
-    adjacency matrices, and :ref:`universal-functions` that are not strictly
+    adjacency matrices, and universal functions that are not strictly
     typed and will work with either a :class:`~retworkx.PyGraph` or
     :class:`~retworkx.PyDiGraph` object. It also includes new algorithm
     functions around matchings for a :class:`~retworkx.PyGraph`, including a