doc: update user guide & documentation for next release (#12)

* doc: add honeycomb-utils page to UG

* doc: add Rust project setup instructions

also, mention honeycomb-utils in index & workspace pages

* doc: update README

* doc: bump version of packages & update honeycomb-core todo list

README.md

@@ -32,11 +32,14 @@ kill $(ps -e | awk '/mdbook/ {print $1}')
 
 ### Rust
 
-Basic structure are provided in the **honeycomb-core** crate. Its content is listed
-in the [user guide][UGHC] and details about its usage can be found in its [Rust documentation][DOCHC]
+The content of each member as well as instructions for usage are available in the [user guide][UGW].
 
-[UGHC]: https://lihpc-computational-geometry.github.io/honeycomb/project-structure/honeycomb-core.html
+- Basic structure are provided in the **honeycomb-core** crate ([Rust Doc][DOCHC]). 
+- Utilities for tests and benchmarks are provided in the **honeycomb-utils** crate ([Rust Doc][DOCHU])
+
+[UGW]: https://lihpc-computational-geometry.github.io/honeycomb/project-structure/workspace.html
 [DOCHC]: https://lihpc-computational-geometry.github.io/honeycomb/honeycomb_core/
+[DOCHU]: https://lihpc-computational-geometry.github.io/honeycomb/honeycomb_utils/
 
 ## Contributing
 

honeycomb-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "honeycomb-core"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 
 [features]

honeycomb-guide/src/SUMMARY.md

@@ -7,6 +7,7 @@
 - [Workspace](./project-structure/workspace.md)
     - [honeycomb-core](./project-structure/honeycomb-core.md)
     - [honeycomb-guide](./project-structure/honeycomb-guide.md)
+    - [honeycomb-utils](./project-structure/honeycomb-utils.md)
 
 # Definitions
 

honeycomb-guide/src/index.md

@@ -11,7 +11,7 @@ The current objective is to write a first implementation in Rust, to then
 improve the structure without having to deal with data races and similar 
 issues, thanks to the language's guarantees.
 
-### Requirements
+### Core Requirements
 
 - **Rust stable release** - *Development started on 1.75, but we might use 
   newer features as the project progresses*
@@ -20,7 +20,37 @@ issues, thanks to the language's guarantees.
 
 #### Rust
 
-...
+The crate is not currently being published on crates.io, meaning you will have
+to clone this repository and add the dependency using the path to the project.
+
+```shell
+# Example: Setting up a new project using honeycomb-core
+
+# Create your project using cargo
+cargo new --bin my_project
+
+# Clone the honeycomb repository
+git clone https://github.com/LIHPC-Computational-Geometry/honeycomb.git
+
+# Add the dependency to your project
+# Version is set to whatever the current version is in the repository
+cd my_project
+cargo add honeycomb-core --path=../honeycomb/honeycomb-core/
+```
+
+The following lines should have appeared in the manifest of your project:
+
+```toml
+# Cargo.toml
+# ...
+
+[dependencies]
+honeycomb-core = { path = "../honeycomb/honeycomb-core/" }
+```
+
+You can also copy-paste the above directly to your manifest. From there, you can
+manually add whichever features your application requires. 
+
 
 #### Documentation
 
@@ -37,6 +67,7 @@ cargo doc --all --no-deps
 ### Documentation
 
 - [honeycomb-core](honeycomb_core/) *Core definitions and tools*
+- [honeycomb-utils](honeycomb_utils/) *Utility routines*
 
 ### References
 

honeycomb-guide/src/project-structure/honeycomb-core.md

@@ -37,10 +37,10 @@ structures:
 
 ## Future additions
 
+- [x] Write structure benchmarks (2D) - done as of **0.1.1**
 - [ ] Add a custom vector type for spatial representation (2D & 3D)
 - [ ] Replace returned `Vec` by an alternative structure or type
   to prevent too many runtime allocations.
-- [ ] Write structure benchmarks (2D)
 - [ ] Add I/O support for mesh formats (2D)
 - [ ] Add orientation checks (2D)
 - [ ] Implement 3D maps

honeycomb-guide/src/project-structure/honeycomb-utils.md

@@ -0,0 +1,75 @@
+# honeycomb-utils
+
+[Documentation](../honeycomb_utils/)
+
+--- 
+
+**honeycomb-utils** is a Rust crate that provides utility functions to
+the user (and developer) in order to write benchmarks and tests more
+easily. A number of benchmarks are already defined in this crate using the 
+[criterion][CRITERION] and [iai-callgrind][IAI] crates. Additionally, 
+one example is provided to illustrate the result of the different *size*
+methods on a given map, as well as a plotting script for the methods' output.
+
+Note that the **iai-callgrind** benchmarks require their runner to be 
+installed as well as Valgrind. Refer to the crate's [README][IAIRM] for 
+detailed instructions.
+
+
+## Usage
+
+### Benchmarks
+
+You can run benchmarks using the following commands:
+
+```shell
+# Run all benchmarks
+cargo bench --benches
+
+# Run a specific benchmark
+cargo bench --bench <BENCHMARK>
+```
+
+The following benchmarks are available:
+
+| Name                          | Type          | Source file                        |
+|-------------------------------|---------------|-----------------------------------|
+| `splitsquaremap-init`         | Criterion     | `benches/splitsquaremap/init.rs`  |
+| `splitsquaremap-shift`        | Criterion     | `benches/splitsquaremap/shift.rs` |
+| `squaremap-init`              | Criterion     | `benches/squaremap/init.rs`       |
+| `squaremap-shift`             | Criterion     | `benches/squaremap/shift.rs`      |
+| `squaremap-splitquads`        | Criterion     | `benches/squaremap/split.rs`      |
+| `prof-twomap-editing`         | Iai-callgrind | `benches/core/twomap/editing.rs`  |
+| `prof-twomap-reading`         | Iai-callgrind | `benches/core/twomap/reading.rs`  |
+| `prof-twomap-sewing-unsewing` | Iai-callgrind | `benches/core/twomap/sewing.rs`   |
+
+A detailed explanation about the purpose of each benchmark is provided at the beginning
+of their respective source files. As a rule of thumb, the **iai-callgrind** benchmarks
+cover individual methods of the structure while **criterion** benchmarks cover higher 
+level computations.
+
+
+### Examples
+
+You can run examples using the following command:
+
+```shell
+# Run a specific example
+cargo run --example <EXAMPLE>
+```
+
+The following examples are available:
+
+| Name           | Description |
+|----------------|-------------|
+| `memory_usage` | Outputs the memory usage of a given map as three *csv* files. These files can be used to generate charts using the `memory_usage.py` script |
+
+
+### Scripts
+
+- `memory_usage.py` - **requires matplotlib** - Plots pie charts using a *csv* file produced by a size method of TwoMap.
+
+
+[CRITERION]: https://github.com/bheisler/criterion.rs
+[IAI]: https://github.com/iai-callgrind/iai-callgrind
+[IAIRM]: https://github.com/iai-callgrind/iai-callgrind?tab=readme-ov-file#installation

honeycomb-guide/src/project-structure/workspace.md

@@ -9,6 +9,7 @@ introduced to the project.
 These entries are members of the Cargo workspace.
 
 - [honeycomb-core](honeycomb-core.html) *Core definitions and tools for combinatorial map implementation*
+- [honeycomb-utils](honeycomb-utils.html) *Utility routines used in benchmarking and testing*
 
 ## Others
 

honeycomb-utils/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "honeycomb-utils"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html