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 1977f66.

---------

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

.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

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.
+///     <https://doi.org/10.1017/CBO9780511815478>
 ///
-/// 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;

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)
+///    <https://arxiv.org/abs/cond-mat/0112143>
 ///
 pub fn dorogovtsev_goltsev_mendes_graph<G, T, F, H, M>(
     n: usize,

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<usize>,
     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<f64>`
-///         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<f64>`]
+///   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)
+///    <https://link.springer.com/article/10.1007/BF00288961>
+/// [^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)
+///    <https://doi.org/10.1016/0020-0190(88)90066-X>
 pub fn steiner_tree<G, F, E>(
     graph: G,
     terminal_nodes: &[G::NodeId],