From 5d28053f31240182d697a6841d595d6e5fcad8f1 Mon Sep 17 00:00:00 2001 From: Etienne Wodey <44871469+airwoodix@users.noreply.github.com> Date: Sat, 30 Nov 2024 19:45:45 +0100 Subject: [PATCH] rustworkx-core: fix docs build warnings (#1333) * core/steiner_tree: fix rustdoc warnings * core/generators/dorogovtsev_goltsev_mendes: fix rustdoc warnings * core/centrality: fix rustdoc warnings * workflows/main: error on warnings during rustworkx-core doc build * Pin Rust to 1.82 for clippy * Revert: Pin Rust to 1.82 to work around #1331 This reverts commit 1977f669fa2bd78ad7baaf5c1bf6f303e992daa6. --------- Co-authored-by: Ivan Carvalho <8753214+IvanIsCoding@users.noreply.github.com> --- .github/workflows/main.yml | 2 + rustworkx-core/src/centrality.rs | 11 +++-- .../dorogovtsev_goltsev_mendes_graph.rs | 17 +++---- rustworkx-core/src/steiner_tree.rs | 44 +++++++++++-------- 4 files changed, 44 insertions(+), 30 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 5579fb21a6..f635c608e3 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -46,6 +46,8 @@ jobs: run: pushd rustworkx-core && cargo test && popd - name: rustworkx-core Docs run: pushd rustworkx-core && cargo doc && popd + env: + RUSTDOCFLAGS: '-D warnings' - uses: actions/upload-artifact@v4 with: name: rustworkx_core_docs diff --git a/rustworkx-core/src/centrality.rs b/rustworkx-core/src/centrality.rs index 47dfd21367..a90876e4df 100644 --- a/rustworkx-core/src/centrality.rs +++ b/rustworkx-core/src/centrality.rs @@ -1073,18 +1073,21 @@ mod test_katz_centrality { /// In the case of a graphs with more than one connected component there is /// an alternative improved formula that calculates the closeness centrality /// as "a ratio of the fraction of actors in the group who are reachable, to -/// the average distance" [^WF]. You can enable this by setting `wf_improved` to `true`. +/// the average distance".[^WF] +/// You can enable this by setting `wf_improved` to `true`. /// -/// [^WF] Wasserman, S., & Faust, K. (1994). Social Network Analysis: +/// [^WF]: Wasserman, S., & Faust, K. (1994). Social Network Analysis: /// Methods and Applications (Structural Analysis in the Social Sciences). -/// Cambridge: Cambridge University Press. doi:10.1017/CBO9780511815478 +/// Cambridge: Cambridge University Press. +/// /// -/// Arguments: +/// # Arguments /// /// * `graph` - The graph object to run the algorithm on /// * `wf_improved` - If `true`, scale by the fraction of nodes reachable. /// /// # Example +/// /// ```rust /// use rustworkx_core::petgraph; /// use rustworkx_core::centrality::closeness_centrality; diff --git a/rustworkx-core/src/generators/dorogovtsev_goltsev_mendes_graph.rs b/rustworkx-core/src/generators/dorogovtsev_goltsev_mendes_graph.rs index 99954f498a..2bd10991bf 100644 --- a/rustworkx-core/src/generators/dorogovtsev_goltsev_mendes_graph.rs +++ b/rustworkx-core/src/generators/dorogovtsev_goltsev_mendes_graph.rs @@ -16,18 +16,19 @@ use super::InvalidInputError; /// Generate a Dorogovtsev-Goltsev-Mendes graph /// -/// Generate a graph following the recursive procedure in [1]. +/// Generate a graph following the recursive procedure by Dorogovtsev, Goltsev, +/// and Mendes[^DGM2002]. /// Starting from the two-node, one-edge graph, iterating `n` times generates -/// a graph with `(3**n + 3) // 2` nodes and `3**n` edges. +/// a graph with `(3^n + 3) // 2` nodes and `3^n` edges. /// +/// # Arguments /// -/// Arguments: -/// -/// * `n` - The number of iterations to perform. n=0 returns the two-node, one-edge graph. +/// * `n` - The number of iterations to perform. `n = 0` returns the two-node, one-edge graph. /// * `default_node_weight` - A callable that will return the weight to use for newly created nodes. /// * `default_edge_weight` - A callable that will return the weight object to use for newly created edges. /// /// # Example +/// /// ```rust /// use rustworkx_core::petgraph; /// use rustworkx_core::generators::dorogovtsev_goltsev_mendes_graph; @@ -43,10 +44,10 @@ use super::InvalidInputError; /// ); /// ``` /// -/// .. [1] S. N. Dorogovtsev, A. V. Goltsev and J. F. F. Mendes +/// [^DGM2002]: S. N. Dorogovtsev, A. V. Goltsev and J. F. F. Mendes /// “Pseudofractal scale-free web” -/// Physical Review E 65, 066122, 2002 -/// https://arxiv.org/abs/cond-mat/0112143 +/// Physical Review E 65, 066122 (2002) +/// /// pub fn dorogovtsev_goltsev_mendes_graph( n: usize, diff --git a/rustworkx-core/src/steiner_tree.rs b/rustworkx-core/src/steiner_tree.rs index f9bdcc60bb..80fab566fd 100644 --- a/rustworkx-core/src/steiner_tree.rs +++ b/rustworkx-core/src/steiner_tree.rs @@ -437,6 +437,9 @@ where Ok(out_edges) } +/// Solution to a minimum Steiner tree problem. +/// +/// This `struct` is created by the [steiner_tree] function. pub struct SteinerTreeResult { pub used_node_indices: HashSet, pub used_edge_endpoints: HashSet<(usize, usize)>, @@ -454,21 +457,25 @@ pub struct SteinerTreeResult { /// complete graph in which each edge is weighted by the shortest path distance /// between nodes in ``graph``. /// -/// This algorithm [1]_ produces a tree whose weight is within a -/// :math:`(2 - (2 / t))` factor of the weight of the optimal Steiner tree -/// where :math:`t` is the number of terminal nodes. The algorithm implemented -/// here is due to [2]_ . It avoids computing all pairs shortest paths but rather -/// reduces the problem to a single source shortest path and a minimum spanning tree -/// problem. +/// This algorithm by Kou, Markowsky, and Berman[^KouMarkowskyBerman1981] +/// produces a tree whose weight is within a `(2 - (2 / t))` factor of +/// the weight of the optimal Steiner tree where `t` is the number of +/// terminal nodes. +/// The algorithm implemented here is due to Mehlhorn[^Mehlhorn1987]. It avoids +/// computing all pairs shortest paths but rather reduces the problem to a +/// single source shortest path and a minimum spanning tree problem. /// -/// Arguments: -/// `graph`: The input graph to compute the steiner tree of -/// `terminal_nodes`: The terminal nodes of the steiner tree -/// `weight_fn`: A callable weight function that will be passed an edge reference -/// for each edge in the graph and it is expected to return a `Result` -/// which if it doesn't error represents the weight of that edge. +/// # Arguments +/// +/// - `graph` - The input graph to compute the Steiner tree of +/// - `terminal_nodes` - The terminal nodes of the Steiner tree +/// - `weight_fn` - A callable weight function that will be passed an edge reference +/// for each edge in the graph and it is expected to return a [`Result`] +/// which if it doesn't error represents the weight of that edge. +/// +/// # Returns /// -/// Returns a custom struct that contains a set of nodes and edges and `None` +/// A custom struct that contains a set of nodes and edges and `None` /// if the graph is disconnected relative to the terminal nodes. /// /// # Example @@ -509,13 +516,14 @@ pub struct SteinerTreeResult { /// let tree = steiner_tree(&input_graph, &terminal_nodes, weight_fn).unwrap().unwrap(); /// ``` /// -/// .. [1] Kou, Markowsky & Berman, +/// [^KouMarkowskyBerman1981]: Kou, Markowsky & Berman, /// "A fast algorithm for Steiner trees" -/// Acta Informatica 15, 141–145 (1981). -/// https://link.springer.com/article/10.1007/BF00288961 -/// .. [2] Kurt Mehlhorn, +/// Acta Informatica 15, 141–145 (1981) +/// +/// [^Mehlhorn1987]: Kurt Mehlhorn, /// "A faster approximation algorithm for the Steiner problem in graphs" -/// https://doi.org/10.1016/0020-0190(88)90066-X +/// Information Processing Letters 27(3), 125-128 (1987) +/// pub fn steiner_tree( graph: G, terminal_nodes: &[G::NodeId],