Enhance traversal docs (#1375)

* Enhance universal bfs_search docs and misc docs fixes

* Enhance docs of non universal bfs_search

* non-universal centrality doc fixes

* New BFS pseudo-code in rustworkx-core

* fixes after looking at docs

* enhance dfs search docs

* formatting

* Fix docs publishing job

* simplify pseudo-code

* enhance dijksra_search docs

* add dijkstra_search doc example

* fix universal dijkstra_search type annotations

* correct description: python code -> psuedo-code

---------

Co-authored-by: Ivan Carvalho <[email protected]>

Author: barakatzir

.github/workflows/docs_dev.yml

@@ -28,12 +28,12 @@ jobs:
       run: |
         tools/build_documentation_dev.sh
     - name: Upload artifact
-      uses: actions/upload-pages-artifact@v2
+      uses: actions/upload-pages-artifact@v3
       with:
         name: html_docs
         path: docs/build/html
     - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3
+      uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_branch: gh-pages

.github/workflows/docs_release.yml

@@ -29,12 +29,12 @@ jobs:
       run: |
         tools/build_documentation_release.sh
     - name: Upload artifact
-      uses: actions/upload-pages-artifact@v2
+      uses: actions/upload-pages-artifact@v3
       with:
         name: html_docs
         path: release_docs/
     - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3
+      uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_branch: gh-pages

rustworkx-core/src/traversal/bfs_visit.rs

@@ -56,29 +56,32 @@ pub enum BfsEvent<N, E> {
 ///
 /// ***Panics** if you attempt to prune a node from its `Finish` event.
 ///
-/// The pseudo-code for the BFS algorithm is listed below, with the annotated
-/// event points, for which the given visitor object will be called with the
-/// appropriate method.
+/// Pseudo-code for the BFS algorithm is listed below, with the annotated event points,
+/// for which the given visitor object will be called with the appropriate method.
 ///
 /// ```norust
+/// // G - graph, s - single source node
 /// BFS(G, s)
-///   for each vertex u in V
-///       color[u] := WHITE
+///   let color be a mapping             // color[u] - vertex u color WHITE/GRAY/BLACK
+///   for each u in G                    // u - vertex in G
+///     color[u] := WHITE                // color all vertices as undiscovered
 ///   end for
-///   color[s] := GRAY
-///   EQUEUE(Q, s)                             discover vertex s
-///   while (Q != Ø)
-///       u := DEQUEUE(Q)
-///       for each vertex v in Adj[u]          (u,v) is a tree edge
-///           if (color[v] = WHITE)
-///               color[v] = GRAY
-///           else                             (u,v) is a non - tree edge
-///               if (color[v] = GRAY)         (u,v) has a gray target
-///                   ...
-///               else if (color[v] = BLACK)   (u,v) has a black target
-///                   ...
-///       end for
-///       color[u] := BLACK                    finish vertex u
+///   let Q be a queue
+///   ENQUEUE(Q, s)
+///   color[s] := GRAY                   // event: Discover(s)
+///   while (Q is not empty)
+///     u := DEQUEUE(Q)
+///     for each v, w in OutEdges(G, u)  // v - target vertex, w - edge weight
+///       if (WHITE = color[v])          // event: TreeEdge(u, v, w)
+///         color[v] := GRAY             // event: Discover(v)
+///         ENQUEUE(Q, v)
+///       else                           // event: NonTreeEdge(u, v, w)
+///         if (GRAY = color[v])         // event: GrayTargetEdge(u, v, w)
+///           ...                       
+///         elif (BLACK = color[v])      // event: BlackTargetEdge(u, v, w)
+///           ...                       
+///     end for
+///     color[u] := BLACK                // event: Finish(u)
 ///   end while
 /// ```
 ///

rustworkx-core/src/traversal/dfs_visit.rs

@@ -65,6 +65,43 @@ pub enum DfsEvent<N, E> {
 ///
 /// ***Panics** if you attempt to prune a node from its `Finish` event.
 ///
+/// Pseudo-code for the DFS algorithm is listed below, with the annotated event points,
+/// for which the given visitor object will be called with the appropriate method.
+///
+/// ```norust
+/// // G - graph, s - single source node
+/// DFS(G, s)
+///   let color be a mapping                        // color[u] - vertex u color WHITE/GRAY/BLACK
+///   for each u in G                               // u - vertex in G
+///     color[u] := WHITE                           // color all as undiscovered
+///   end for
+///   time := 0
+///   let S be a stack
+///   PUSH(S, (s, iterator of OutEdges(G, s)))      // S - stack of vertices and edge iterators
+///   color[s] := GRAY                              // event: Discover(s, time)
+///   while (S is not empty)
+///     let (u, iterator) := LAST(S)
+///     flag := False                               // whether edge to undiscovered vertex found
+///     for each v, w in iterator                   // v - target vertex, w - edge weight
+///       if (WHITE = color[v])                     // event: TreeEdge(u, v, w)
+///         time := time + 1
+///         color[v] := GRAY                        // event: Discover(v, time)
+///         flag := True
+///         break
+///       elif (GRAY = color[v])                    // event: BackEdge(u, v, w)
+///         ...
+///       elif (BLACK = color[v])                   // event: CrossForwardEdge(u, v, w)
+///         ...
+///     end for
+///     if (flag is True)
+///       PUSH(S, (v, iterator of OutEdges(G, v)))
+///     elif (flag is False)
+///       time := time + 1
+///       color[u] := BLACK                         // event: Finish(u, time)
+///       POP(S)
+///   end while
+/// ```
+///
 /// # Example returning `Control`.
 ///
 /// Find a path from vertex 0 to 5, and exit the visit as soon as we reach

rustworkx-core/src/traversal/dijkstra_visit.rs

@@ -94,25 +94,30 @@ pub enum DijkstraEvent<N, E, K> {
 /// appropriate method.
 ///
 /// ```norust
-/// DIJKSTRA(G, source, weight)
-///   for each vertex u in V
-///       d[u] := infinity
-///       p[u] := u
-///   end for
-///   d[source] := 0
-///   INSERT(Q, source)
-///   while (Q != Ø)
-///       u := EXTRACT-MIN(Q)                         discover vertex u
-///       for each vertex v in Adj[u]                 examine edge (u,v)
-///           if (weight[(u,v)] + d[u] < d[v])        edge (u,v) relaxed
-///               d[v] := weight[(u,v)] + d[u]
-///               p[v] := u
-///               DECREASE-KEY(Q, v)
-///           else                                    edge (u,v) not relaxed
-///               ...
-///           if (d[v] was originally infinity)
-///               INSERT(Q, v)
-///       end for                                     finish vertex u
+/// // G - graph, s - single source node, weight - edge cost function
+/// DIJKSTRA(G, s, weight)
+///   let score be empty mapping
+///   let visited be empty set
+///   let Q be a priority queue
+///   score[s] := DEFAULT_COST
+///   PUSH(Q, (score[s], s))                // only score determines the priority
+///   while Q is not empty
+///     cost, u := POP-MIN(Q)
+///     if u in visited
+///       continue
+///     PUT(visited, u)                     // event: Discover(u, cost)
+///     for each _, v, w in OutEdges(G, u)  // v - target vertex, w - edge weight
+///       ...                               // event: ExamineEdge(u, v, w)
+///       if v in visited
+///         continue
+///       next_cost = cost + weight(w)
+///       if {(v is key in score)
+///           and (score[v] <= next_cost)}  // event: EdgeNotRelaxed(u, v, w)
+///         ...                             
+///       else:                             // v not scored or scored higher
+///         score[v] = next_cost            // event: EdgeRelaxed(u, v, w)
+///         PUSH(Q, (next_cost, v))
+///     end for                             // event: Finish(u)
 ///   end while
 /// ```
 ///