doc: update rustdoc, user guide & readme (#19)

* chore: bump version to 0.1.3 * doc: add honeycomb-render section to UG * doc: change the Cargo toml example to include other workspace member * doc: add content to honeycomb-render section * doc: add documentation of the SmaaMode enum * doc: add RenderParameters documentation * doc: add Runner documentation * doc: add module-level documentation across honeycomb-render * doc: finish UG section of honeycomb-render * doc: update honeycomb-core section in UG * doc: update README * chore: update changelog file & create 0.1.3 section * doc: update examples to use ? operator instead of unwrap suggestion from @cedricchevalier19 * remove empty line in Coords2 example Co-authored-by: Cédric Chevalier <[email protected]> * doc: add link to Coords2 example in user guide * chore: update changelog --------- Co-authored-by: Cédric Chevalier <[email protected]>
LIHPC-Computational-Geometry · Mar 18, 2024 · a2b9b6c · a2b9b6c
1 parent 48d0713
commit a2b9b6c
Show file tree

Hide file tree

Showing 18 changed files with 181 additions and 66 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,22 +2,41 @@
 
 ## To be released
 
-### Repository Changes
-
 ...
 
+---
+
+## 0.1.3
+
 ### New Features
 
 #### honeycomb-core
 
+<sup>core definitions and tools for combinatorial map implementation</sup>
+
 - `Orbit<'a, const N_MARKS: usize, T: CoordsFloat>` - Generic implementation for
   2D orbit computations. The structure itself only contains meta-data, the orbit
-  computation is done through the `Iterator` trait implementation.
+  computation is done through the `Iterator` trait implementation (#18)
 - `OrbitPolicy<'a>` - Enum used to specify the beta functions used by an orbit.
-  It currently does not not support compositions.
+  It currently does not support compositions (#18)
 - New (temporary?) method for `TwoMap`: `beta_runtime`. It works by redirecting
   to the original `beta` method, using match block and a beta identifier provided
-  at runtime.
+  at runtime (#18)
+
+#### honeycomb-guide
+
+<sup>**mdbook**-based user guide with information regarding usage & non-code-related
+aspects of the project</sup>
+
+- update content of the workspace section to include new member (#19)
+- update **honeycomb-core**'s page content (#19)
+
+#### honeycomb-render (new member)
+
+<sup>visualization tool for combinatorial maps</sup>
+
+- implement `TwoMap` rendering code
+- add examples illustrating basic usage
 
 ---
 
@@ -32,6 +51,8 @@
 
 #### honeycomb-core
 
+<sup>core definitions and tools for combinatorial map implementation</sup>
+
 - `Coords2<T: CoordsFloat>` - Custom 2D coordinates representation using a
   generic type for inner value.
 - refactor two attributes of `TwoMap`:
@@ -40,10 +61,15 @@
 
 #### honeycomb-guide
 
+<sup>**mdbook**-based user guide with information regarding usage & non-code-related
+aspects of the project</sup>
+
 - update usage instructions
 
 #### honeycomb-utils
 
+<sup>utility routines used in benchmarking and testing</sup>
+
 - update content according to features introduced in #15, #16
 
 ---
@@ -52,22 +78,31 @@
 
 ### Repository Changes
 
-- new project members: `honeycomb-utils` (#10)
 - new CI workflow:
     - `bench`: run hardware-counter based benchmarks on new version release
 
 ### New Features
 
 #### honeycomb-core
 
+<sup>core definitions and tools for combinatorial map implementation</sup>
+
 - introduce `benchmarking_utils` feature, used to compile additional methods &
   trait implementation useful for benchmarking
 
 #### honeycomb-guide
 
-- update content (#5, #12)
+<sup>**mdbook**-based user guide with information regarding usage & non-code-related
+aspects of the project.</sup>
 
-#### honeycomb-utils
+- complete (partially) definition sections (#5)
+- add documentation for the core implementatiosn (#5)
+- add usage instructions (#12)
+- add `honeycomb-utils` section (#12)
+
+#### honeycomb-utils (new member)
+
+<sup>utility routines used in benchmarking and testing</sup>
 
 - benchmarks for the `TwoMap` structure and methods (#10, #11)
 - utility functions for benchmarking and testing.
@@ -83,19 +118,20 @@
 
 ### Repository Changes
 
-- new project members: `honeycomb-core`, `honeycomb-guide`
 - new CI workflows:
     - `doc`: build & deploy user guide and code documentation
     - `rust-test`: run Rust tests, format checker & linter (`clippy`)
 
 ### New Features
 
-#### honeycomb-core
+#### honeycomb-core (new member)
+
+<sup>core definitions and tools for combinatorial map implementation</sup>
 
 - `TwoMap` - basic 2D combinatorial map implementation
 - full documentation support & deployment
 
-#### honeycomb-guide
+#### honeycomb-guide (new member)
 
-- **mdbook**-based user guide with information regarding usage &
-  non-code-related aspects of the project.
+<sup>**mdbook**-based user guide with information regarding usage & non-code-related
+aspects of the project</sup>
diff --git a/README.md b/README.md
@@ -1,18 +1,18 @@
 # Honeycomb
 
-Honeycomb aims to provide a safe, efficient and scalable implementation of 
+Honeycomb aims to provide a safe, efficient and scalable implementation of
 combinatorial maps for meshing applications. More specifically, the goal is
-to converge towards a (or multiple) structure(s) adapted to algorithms 
+to converge towards a (or multiple) structure(s) adapted to algorithms
 exploiting GPUs and many-core architectures.
 
-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 
+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.
 
 ## Usage
 
-The [user guide][UG] provides an overview of everything available in the 
-project. It can be generated offline using **mdbook**: 
+The [user guide][UG] provides an overview of everything available in the
+project. It can be generated offline using **mdbook**:
 
 ```shell
 # Serve the doc on a local server
@@ -34,13 +34,18 @@ kill $(ps -e | awk '/mdbook/ {print $1}')
 
 The content of each member as well as instructions for usage are available in the [user guide][UGW].
 
-- Basic structure are provided in the **honeycomb-core** crate ([Rust Doc][DOCHC]). 
+- Basic structures 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])
+- A visualing tool is provided in the **honeycomb-render** crate ([Rust Doc][DOCHR]).
 
 [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/
 
+[DOCHR]: https://lihpc-computational-geometry.github.io/honeycomb/honeycomb_render/
+
 ## Contributing
 
 ## License
diff --git a/honeycomb-core/Cargo.toml b/honeycomb-core/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "honeycomb-core"
-version = "0.1.2"
+version = "0.1.3"
 edition = "2021"
 
 [features]

diff --git a/honeycomb-core/src/coords.rs b/honeycomb-core/src/coords.rs
@@ -54,6 +54,8 @@ pub enum CoordsError {
 /// # Example
 ///
 /// ```rust
+/// # use honeycomb_core::CoordsError;
+/// # fn main() -> Result<(), CoordsError> {
 /// use honeycomb_core::{Coords2, FloatType};
 ///
 /// let unit_x = Coords2::unit_x();
@@ -66,7 +68,9 @@ pub enum CoordsError {
 /// let x_plus_y: Coords2<FloatType> = unit_x + unit_y;
 ///
 /// assert_eq!(x_plus_y.norm(), two.sqrt());
-/// assert_eq!(x_plus_y.unit_dir().unwrap(), Coords2::from((1.0 / two.sqrt(), 1.0 / two.sqrt())));
+/// assert_eq!(x_plus_y.unit_dir()?, Coords2::from((1.0 / two.sqrt(), 1.0 / two.sqrt())));
+/// # Ok(())
+/// # }
 /// ```
 ///
 #[derive(Debug, Clone, Copy, Default, PartialEq)]

diff --git a/honeycomb-core/src/lib.rs b/honeycomb-core/src/lib.rs
@@ -24,7 +24,7 @@ pub mod twomap;
 
 // ------ RE-EXPORTS
 
-pub use coords::{Coords2, CoordsFloat, FloatType};
+pub use coords::{Coords2, CoordsError, CoordsFloat, FloatType};
 pub use dart::{DartIdentifier, NULL_DART_ID};
 pub use embed::{
     FaceIdentifier, SewPolicy, UnsewPolicy, Vertex2, VertexIdentifier, VolumeIdentifier,

diff --git a/honeycomb-core/src/twomap.rs b/honeycomb-core/src/twomap.rs
@@ -88,6 +88,8 @@ const TWO_MAP_BETA: usize = 3;
 /// progressive changes applied to the structure.
 ///
 /// ```
+/// # use honeycomb_core::twomap::MapError;
+/// # fn main() -> Result<(), MapError> {
 /// use honeycomb_core::{ DartIdentifier, SewPolicy, TwoMap, UnsewPolicy, VertexIdentifier, NULL_DART_ID, Orbit, OrbitPolicy};
 ///
 /// // --- Map creation
@@ -100,9 +102,9 @@ const TWO_MAP_BETA: usize = 3;
 /// let (v1, v2, v3): (VertexIdentifier, VertexIdentifier, VertexIdentifier) = (0, 1, 2);
 ///
 /// // place the vertices in space
-/// map.set_vertex(v1, [0.0, 0.0]).unwrap();
-/// map.set_vertex(v2, [0.0, 10.0]).unwrap();
-/// map.set_vertex(v3, [10.0, 0.0]).unwrap();
+/// map.set_vertex(v1, [0.0, 0.0])?;
+/// map.set_vertex(v2, [0.0, 10.0])?;
+/// map.set_vertex(v3, [10.0, 0.0])?;
 /// // associate dart to vertices
 /// map.set_vertexid(d1, v1);
 /// map.set_vertexid(d2, v2);
@@ -164,8 +166,8 @@ const TWO_MAP_BETA: usize = 3;
 /// let v4 = map.add_vertex(Some([15.0, 0.0].into())); // v4
 /// let v5 = map.add_vertices(2); // v5, v6
 /// let v6 = v5 + 1;
-/// map.set_vertex(v5, [5.0, 10.0]).unwrap(); // v5
-/// map.set_vertex(v6, [15.0, 10.0]).unwrap(); // v6
+/// map.set_vertex(v5, [5.0, 10.0])?; // v5
+/// map.set_vertex(v6, [15.0, 10.0])?; // v6
 /// // associate dart to vertices
 /// map.set_vertexid(d4, v4);
 /// map.set_vertexid(d5, v5);
@@ -202,7 +204,7 @@ const TWO_MAP_BETA: usize = 3;
 /// // --- (c)
 ///
 /// // shift the position of d6 to build a square using the two faces
-/// map.set_vertex(map.vertexid(d6), [10.0, 10.0]).unwrap();
+/// map.set_vertex(map.vertexid(d6), [10.0, 10.0])?;
 ///
 /// // --- (d)
 ///
@@ -248,6 +250,8 @@ const TWO_MAP_BETA: usize = 3;
 /// assert!(new_two_cell.contains(&d3));
 /// assert_eq!(new_two_cell.len(), 4);
 ///
+/// # Ok(())
+/// # }
 /// ```
 ///
 #[cfg_attr(feature = "benchmarking_utils", derive(Clone))]

diff --git a/honeycomb-guide/src/SUMMARY.md b/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-render](./project-structure/honeycomb-render.md)
     - [honeycomb-utils](./project-structure/honeycomb-utils.md)
 
 # Definitions

diff --git a/honeycomb-guide/src/index.md b/honeycomb-guide/src/index.md
@@ -31,10 +31,10 @@ following line to the manifest of the project:
 [dependencies]
 # Other dependencies...
 honeycomb-core = { git = "https://github.com/LIHPC-Computational-Geometry/honeycomb.git" }
+honeycomb-utils = { git = "https://github.com/LIHPC-Computational-Geometry/honeycomb.git" }
+honeycomb-render = { git = "https://github.com/LIHPC-Computational-Geometry/honeycomb.git" }
 ```
 
-Optionally, you can add other member(s) of the workspace and specify which version to use.
-
 #### Documentation
 
 You can generate this documentation locally using **mdbook** and **cargo doc**:
@@ -50,6 +50,7 @@ cargo doc --all --no-deps
 ### Documentation
 
 - [honeycomb-core](honeycomb_core/) *Core definitions and tools*
+- [honeycomb-render](honeycomb_render/) *Visualization tool*
 - [honeycomb-utils](honeycomb_utils/) *Utility routines*
 
 ### References

diff --git a/honeycomb-guide/src/project-structure/honeycomb-core.md b/honeycomb-guide/src/project-structure/honeycomb-core.md
@@ -14,6 +14,7 @@ representation.
 A quickstart example encompassing most features is provided for the following
 structures:
 
+- [Coords2](../honeycomb_core/struct.Coords2.html#example)
 - [TwoMap](../honeycomb_core/twomap/struct.TwoMap.html#example)
 
 ## Content
@@ -22,6 +23,7 @@ structures:
 
 - **TwoMap**: 2D combinatorial map implementation
 - **Coords2**: 2D coordinates implementation
+- **Orbit**: Generic 2D implementation for orbit computation
 
 ### Aliases
 
@@ -33,15 +35,10 @@ structures:
 
 ### Enums
 
+- **OrbitPolicy**: Orbit parameterization.
 - **SewPolicy**: Logic to follow for the geometrical part of the sewing operation.
 - **UnsewPolicy**: Logic to follow for the geometrical part of the unsewing operation.
 
-## Future additions
+### Traits
 
-- [x] Write structure benchmarks (2D) - done as of **0.1.1**
-- [x] Add a custom vector type for spatial representation (2D)
-- [x] Add orientation ~checks~ assertions (2D)
-- [ ] Replace returned `Vec` by an alternative structure or type
-  to prevent too many runtime allocations.
-- [ ] Add I/O support for mesh formats (2D)
-- [ ] Implement 3D maps
+- **CoordsFloat**: Common trait implemented by types used for coordinate representation.
diff --git a/honeycomb-guide/src/project-structure/honeycomb-render.md b/honeycomb-guide/src/project-structure/honeycomb-render.md
@@ -0,0 +1,37 @@
+# honeycomb-render
+
+[Documentation](../honeycomb_render/)
+
+--- 
+
+**honeycomb-render** is a Rust crate that provides a simple visualization framework
+to allow the user to render their combinatorial map. It is designed to be used
+directly in the code by reading data through a reference to the map (as opposed to
+a binary that would read serialized data).
+
+## Usage
+
+### Quickstart
+
+Because this crate is meant to be used in tandem with other members of the workspace,
+no quickstart example is provided in the documentation. Instead, standalone examples
+provided in the crate cover basic usage and parameterization.
+
+### 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                                                                      |
+|-------------------------|----------------------------------------------------------------------------------|
+| `render_default_no_aa`  | Render a hardcoded arrow without anti-aliasing                                   |
+| `render_default_smaa1x` | Render a hardcoded arrow with anti-aliasing                                      |
+| `render_splitsquaremap` | Render a map generated using functions provided by the **honeycomb-utils** crate |
+| `render_squaremap`      | Render a map generated using functions provided by the **honeycomb-utils** crate |
+
diff --git a/honeycomb-guide/src/project-structure/workspace.md b/honeycomb-guide/src/project-structure/workspace.md
@@ -1,20 +1,21 @@
 # Workspace
 
-The project root is organized using Cargo workspaces at 
-the moment. This may change when other languages are 
+The project root is organized using Cargo workspaces at
+the moment. This may change when other languages are
 introduced to the project.
 
 ## Members
 
 These entries are members of the Cargo workspace.
 
 - [honeycomb-core](honeycomb-core.html) *Core definitions and tools for combinatorial map implementation*
+- [honeycomb-render](honeycomb-render.html) *Visualization tool for combinatorial map*
 - [honeycomb-utils](honeycomb-utils.html) *Utility routines used in benchmarking and testing*
 
 ## Others
 
-These entries are additional sections that are not linked to 
-the project through Cargo, most likely because they require a 
+These entries are additional sections that are not linked to
+the project through Cargo, most likely because they require a
 different building process.
 
 - [honeycomb-guide](honeycomb-guide.html) *Source files of the user guide*