Docs and consistency cleanup for rustworkx-core generators

rustworkx-core/src/generators/barbell_graph.rs

@@ -16,36 +16,33 @@ use petgraph::data::{Build, Create};
 use petgraph::visit::{Data, NodeIndexable, NodeRef};
 
 use super::utils::get_num_nodes;
-use super::utils::pairwise;
 use super::InvalidInputError;
+use crate::utils::pairwise;
 
-/// Generate an undirected barbell graph where two identical mesh graphs are
+/// Generate a barbell graph where two identical complete graphs are
 /// connected by a path.
 ///
-/// .. note::
-///
-///   If neither `num_path_nodes` nor `path_weights` (described below) is not specified
-///   then this is equivalent to two mesh graphs joined together.
+///   If neither `num_path_nodes` nor `path_weights` (described below) are
+///   specified, then this is equivalent to two complete graphs joined together.
 ///
 /// Arguments:
 ///
 /// * `num_mesh_nodes` - The number of nodes to generate the mesh graph
 ///     with. Node weights will be None if this is specified. If both
-///     `num_mesh_nodes` and `mesh_weights` are set this will be ignored and
+///     `num_mesh_nodes` and `mesh_weights` are set, this will be ignored and
 ///     `mesh_weights` will be used.
 /// * `num_path_nodes` - The number of nodes to generate the path
 ///     with. Node weights will be None if this is specified. If both
-///     `num_path_nodes` and `path_weights` are set this will be ignored and
+///     `num_path_nodes` and `path_weights` are set, this will be ignored and
 ///     `path_weights` will be used.
 /// * `mesh_weights` - A list of node weights for the mesh graph. If both
-///     `num_mesh_nodes` and `mesh_weights` are set `num_mesh_nodes` will
+///     `num_mesh_nodes` and `mesh_weights` are set, `num_mesh_nodes` will
 ///     be ignored and `mesh_weights` will be used.
 /// * `path_weights` - A list of node weights for the path. If both
-///     `num_path_nodes` and `path_weights` are set `num_path_nodes` will
+///     `num_path_nodes` and `path_weights` are set, `num_path_nodes` will
 ///     be ignored and `path_weights` will be used.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if weights are specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if node weights are specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
 ///
@@ -147,7 +144,7 @@ where
         }
     };
     let pathlen = path_nodes.len();
-    if pathlen > 0 {
+    if !path_nodes.is_empty() {
         graph.add_edge(
             graph.from_index(meshlen - 1),
             graph.from_index(meshlen),

rustworkx-core/src/generators/binomial_tree_graph.rs

@@ -21,15 +21,14 @@ use super::InvalidInputError;
 ///
 /// * `order` - The order of the binomial tree.
 /// * `weights` - A `Vec` of node weight objects. If the number of weights is
-///     less than 2**order extra nodes with None will be appended.
+///     less than 2**order, extra nodes with None will be appended.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/complete_graph.rs

@@ -21,12 +21,11 @@ use super::InvalidInputError;
 /// Arguments:
 ///
 /// * `num_nodes` - The number of nodes to create a complete graph for. Either this or
-///     `weights must be specified. If both this and `weights are specified, weights
+///     `weights` must be specified. If both this and `weights` are specified, `weights`
 ///     will take priorty and this argument will be ignored
 /// * `weights` - A `Vec` of node weight objects.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
 ///

rustworkx-core/src/generators/cycle_graph.rs

@@ -21,17 +21,16 @@ use super::InvalidInputError;
 /// Arguments:
 ///
 /// * `num_nodes` - The number of nodes to create a cycle graph for. Either this or
-///     `weights must be specified. If both this and `weights are specified, weights
+///     `weights` must be specified. If both this and `weights` are specified, `weights`
 ///     will take priorty and this argument will be ignored.
 /// * `weights` - A `Vec` of node weight objects.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/full_rary_tree_graph.rs

@@ -18,21 +18,22 @@ use petgraph::visit::{Data, NodeIndexable};
 
 use super::InvalidInputError;
 
-/// Creates a full r-ary tree of `n` nodes.
+/// Generate a full r-ary tree of `n` nodes.
 /// Sometimes called a k-ary, n-ary, or m-ary tree.
 ///
+/// Arguments:
+///
 /// * `branching factor` - The number of children at each node.
 /// * `num_nodes` - The number of nodes in the graph.
 /// * `weights` - A list of node weights. If the number of weights is
-///     less than n, extra nodes with with None weight will be appended.
+///     less than n, extra nodes with None weight will be appended.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/grid_graph.rs

@@ -21,7 +21,7 @@ use super::InvalidInputError;
 ///
 /// * `rows` - The number of rows to generate the graph with.
 ///     If specified, cols also need to be specified.
-/// * `cols`: The number of rows to generate the graph with.
+/// * `cols`: The number of columns to generate the graph with.
 ///     If specified, rows also need to be specified. rows*cols
 ///     defines the number of nodes in the graph.
 /// * `weights`: A `Vec` of node weights. Nodes are filled row wise.
@@ -32,11 +32,10 @@ use super::InvalidInputError;
 ///     If number of nodes(rows*cols) is greater than length of
 ///     weights list, extra nodes with None weight are appended.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
 ///     If the graph is undirected this will result in a parallel edge.
 ///

rustworkx-core/src/generators/heavy_hex_graph.rs

@@ -17,53 +17,53 @@ use petgraph::visit::{Data, NodeIndexable};
 
 use super::InvalidInputError;
 
-/// Generate an undirected heavy hex graph. Fig. 2 of
-/// https://arxiv.org/abs/1907.09528
-/// An ASCII diagram of the graph is given by:
-///
-/// .. note::
+/// Generate a heavy hex graph.
 ///
+/// Fig. 2 of <https://arxiv.org/abs/1907.09528>
+/// An ASCII diagram of the graph is given by:
+/// ```text
 ///    ... D-S-D   D ...
-///         |   |   |
-///     ...-F   F-S-F ...
-///         |   |   |
-///     ... D   D   D ...
-///         |   |   |
-///     ... F-S-F   F-...
-///         |   |   |
-///         .........
-///         |   |   |
-///     ... D   D   D ...
-///         |   |   |
-///     ...-F   F-S-F ...
-///         |   |   |
-///     ... D   D   D ...
-///         |   |   |
-///     ... F-S-F   F-...
-///         |   |   |
-///         .........
-///         |   |   |
-///     ... D   D   D ...
-///         |   |   |
-///     ...-F   F-S-F ...
-///         |   |   |
-///     ... D   D   D ...
-///         |   |   |
-///     ... F-S-F   F-...
-///         |   |   |
-///     ... D   D-S-D ...
+///        |   |   |
+///    ...-F   F-S-F ...
+///        |   |   |
+///    ... D   D   D ...
+///        |   |   |
+///    ... F-S-F   F-...
+///        |   |   |
+///        .........
+///        |   |   |
+///    ... D   D   D ...
+///        |   |   |
+///    ...-F   F-S-F ...
+///        |   |   |
+///    ... D   D   D ...
+///        |   |   |
+///    ... F-S-F   F-...
+///        |   |   |
+///        .........
+///        |   |   |
+///    ... D   D   D ...
+///        |   |   |
+///    ...-F   F-S-F ...
+///        |   |   |
+///    ... D   D   D ...
+///        |   |   |
+///    ... F-S-F   F-...
+///        |   |   |
+///    ... D   D-S-D ...
+///```
 ///
+/// Arguments:
 ///
-/// * `d` - Distance of the code. If ``d`` is set to ``1`` a graph with a
-///     single node will be returned. d must be an odd number.
+/// * `d` - Distance of the code. If `d` is set to `1` a graph with a
+///     single node will be returned. `d` must be an odd number.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/heavy_square_graph.rs

@@ -17,38 +17,42 @@ use petgraph::visit::{Data, NodeIndexable};
 
 use super::InvalidInputError;
 
-/// Generate an directed heavy square graph. Fig. 6 of
-/// https://arxiv.org/abs/1907.09528.
-/// An ASCII diagram of the graph is given by:
-///
-/// .. note::
+/// Generate a heavy square graph.
 ///
+/// Fig. 6 of <https://arxiv.org/abs/1907.09528>
+/// An ASCII diagram of the graph is given by:
+/// ```text
 ///    ...       S   ...
 ///       \     / \
-///        ... D   D   D ...
-///            |   |   |
-///        ... F-S-F-S-F-...
-///            |   |   |
-///        ... D   D   D ...
-///            |   |   |
-///        ... F-S-F-S-F-...
-///            |   |   |
-///            .........
-///            |   |   |
-///        ... D   D   D ...
-///             \ /     \
-///        ...   S       ...
-///
+///    ... D   D   D ...
+///        |   |   |
+///    ... F-S-F-S-F-...
+///        |   |   |
+///    ... D   D   D ...
+///        |   |   |
+///    ... F-S-F-S-F-...
+///        |   |   |
+///        .........
+///        |   |   |
+///    ... D   D   D ...
+///         \ /     \
+///    ...   S       ...
+/// ```
 /// NOTE: This function generates the four-frequency variant of the heavy square code.
-/// This function implements Fig 10.b left of the `paper <https://arxiv.org/abs/1907.09528>`_.
+/// This function implements Fig 10.b left of the paper <https://arxiv.org/abs/1907.09528>.
 /// This function doesn't support the variant Fig 10.b right.
 ///
-/// :param int d: distance of the code. If ``d`` is set to ``1`` a
-///     :class:`~rustworkx.PyDiGraph` with a single node will be returned.
-/// :param bool multigraph: When set to False the output
-///     :class:`~rustworkx.PyDiGraph` object will not be not be a multigraph and
-///     won't  allow parallel edges to be added. Instead
-///     calls which would create a parallel edge will update the existing edge.
+/// Arguments:
+///
+/// * `d` - Distance of the code. If `d` is set to `1` a graph with a
+///     single node will be returned. `d` must be an odd number.
+/// * `default_node_weight` - A callable that will return the weight to use
+///     for newly created nodes. This is ignored if `weights` is specified.
+/// * `default_edge_weight` - A callable that will return the weight object
+///     to use for newly created edges.
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
+///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust

rustworkx-core/src/generators/hexagonal_lattice_graph.rs

@@ -24,13 +24,12 @@ use super::InvalidInputError;
 /// * `rows` - The number of rows to generate the graph with.
 /// * `cols` - The number of columns to generate the graph with.
 /// * `default_node_weight` - A callable that will return the weight to use
-///     for newly created nodes. This is ignored if `weights` is specified,
-///     as the weights from that argument will be used instead.
+///     for newly created nodes. This is ignored if `weights` is specified.
 /// * `default_edge_weight` - A callable that will return the weight object
 ///     to use for newly created edges.
-/// * `bidirectional` - Whether edges are added bidirectionally, if set to
+/// * `bidirectional` - Whether edges are added bidirectionally. If set to
 ///     `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
-///     If the graph is undirected this will result in a pallel edge.
+///     If the graph is undirected this will result in a parallel edge.
 ///
 /// # Example
 /// ```rust