feat: add a main crate to provide a clean user API (#160)

* add new member with subcrates re-exports

* explicitly re-export core items instead of using its prelude

* add documentation for the new crate

* add nightly feature documentation

it should work the way this is fixed:
rust-lang/rust#96166

* exclude user crate from coverage CI

* fix copypaste mistake in CI

* add links to important items in crate-level doc

Author: imrn99

.github/workflows/coverage.yml

@@ -32,12 +32,22 @@ jobs:
       # generate raw coverage data
       # excluding the benchmark / example crates to remove some bias
       - name: Build code
-        run: cargo build --all-features --workspace --exclude honeycomb-benches --exclude honeycomb-examples --exclude honeycomb-render
+        run: |
+          cargo build --all-features --workspace \
+            --exclude honeycomb \
+            --exclude honeycomb-benches \
+            --exclude honeycomb-examples \
+            --exclude honeycomb-render
         env:
           RUSTFLAGS: "-Cinstrument-coverage"
           LLVM_PROFILE_FILE: "cargo-test-%p-%m.profraw"
       - name: Run tests
-        run: cargo test --all-features --workspace --exclude honeycomb-benches --exclude honeycomb-examples --exclude honeycomb-render
+        run: |
+          cargo test --all-features --workspace \
+            --exclude honeycomb \
+            --exclude honeycomb-benches \
+            --exclude honeycomb-examples \
+            --exclude honeycomb-render
         env:
           RUSTFLAGS: "-Cinstrument-coverage"
           LLVM_PROFILE_FILE: "cargo-test-%p-%m.profraw"

Cargo.toml

@@ -3,6 +3,7 @@
 resolver = "2"
 members = [
     "benches",
+    "honeycomb",
     "honeycomb-core",
     "honeycomb-kernels",
     "honeycomb-render",
@@ -26,6 +27,7 @@ authors = [
 
 [workspace.dependencies]
 # members
+honeycomb = { version = "0.5.0", path = "./honeycomb" }
 honeycomb-benches = { version = "0.5.0", path = "./benches" }
 honeycomb-core = { version = "0.5.0", path = "./honeycomb-core" }
 honeycomb-kernels = { version = "0.5.0", path = "./honeycomb-kernels" }
@@ -59,4 +61,4 @@ debug = true
 
 [profile.profiling]
 inherits = "release"
-debug = true
+debug = true

honeycomb/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "honeycomb"
+edition.workspace = true
+license.workspace = true
+version.workspace = true
+homepage.workspace = true
+repository.workspace = true
+readme.workspace = true
+description.workspace = true
+categories.workspace = true
+keywords.workspace = true
+authors.workspace = true
+publish = true
+
+[features]
+default = ["kernels"]
+kernels = ["dep:honeycomb-kernels"]
+render = ["dep:honeycomb-render"]
+
+[dependencies]
+honeycomb-core = { workspace = true, features = ["io", "utils"] }
+honeycomb-kernels = { workspace = true, optional = true }
+honeycomb-render = { workspace = true, optional = true }

honeycomb/src/build.rs

@@ -0,0 +1,18 @@
+#[rustversion::nightly]
+fn set_rustc_channel_cfg() -> &'static str {
+    "nightly"
+}
+
+#[rustversion::beta]
+fn set_rustc_channel_cfg() -> &'static str {
+    "beta"
+}
+
+#[rustversion::stable]
+fn set_rustc_channel_cfg() -> &'static str {
+    "stable"
+}
+
+fn main() {
+    println!("cargo:rustc-cfg={}", set_rustc_channel_cfg());
+}

honeycomb/src/lib.rs

@@ -0,0 +1,75 @@
+//! # honeycomb
+//!
+//! 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 exploiting GPU and many-core architectures.
+//!
+//! ## Structure
+//!
+//! This crate acts as the user-facing API, re-exporting components and items implemented in the
+//! following sub-crates:
+//!
+//! - `honeycomb_core` -- core structures implementations
+//! - `honeycomb_kernels` -- algorithm implementations
+//! - `honeycomb_render` -- visual debugging tool
+//!
+//! ## Features
+//!
+//! Two features can be enabled to control which implementations are exposed:
+//!
+//! - `kernels` -- content from the `honeycomb_kernels` crate
+//! - `render` -- content from the `honeycomb_render` crate
+//!
+//! Note that:
+//! - the `kernels` feature is enabled by default since it does not require any more dependencies
+//!   than the core crate.
+//! - the `render` feature is disabled by default; enabling it significantly lengthen the
+//!   dependency tree as well as the compilation time.
+//!
+//! ## Quickstart
+//!
+//! For usage examples, refer to examples hosted in the repository; there also are documentation
+//! examples for important items:
+//!
+//! - [`CMap2`][honeycomb_core::cmap::CMap2]
+//! - [`CMapBuilder`][honeycomb_core::cmap::CMapBuilder]
+//! - [`grisubal`][`honeycomb_kernels::grisubal`]
+
+// --- enable doc_auto_cfg feature if compiling in nightly
+#![allow(unexpected_cfgs)]
+#![cfg_attr(nightly, feature(doc_auto_cfg))]
+
+pub use honeycomb_core as core;
+
+#[cfg(feature = "kernels")]
+pub use honeycomb_kernels as kernels;
+
+#[cfg(feature = "render")]
+pub use honeycomb_render as render;
+
+/// commonly used items
+///
+/// This module contains all items commonly used to write a program using combinatorial maps.
+/// These items are re-exported from their original crates for ease of use and should cover
+/// all basic use cases.
+pub mod prelude {
+    // ------ CORE RE-EXPORTS
+
+    pub use honeycomb_core::attributes::{AttributeBind, AttributeUpdate};
+    pub use honeycomb_core::cmap::{
+        BuilderError, CMap2, CMapBuilder, CMapError, DartIdentifier, EdgeIdentifier,
+        FaceIdentifier, GridDescriptor, Orbit2, OrbitPolicy, VertexIdentifier, VolumeIdentifier,
+        NULL_DART_ID, NULL_EDGE_ID, NULL_FACE_ID, NULL_VERTEX_ID, NULL_VOLUME_ID,
+    };
+    pub use honeycomb_core::geometry::{CoordsError, CoordsFloat, Vector2, Vertex2};
+
+    // ------ KERNELS RE-EXPORTS
+
+    #[cfg(feature = "kernels")]
+    pub use honeycomb_kernels::grisubal;
+
+    // ------ RENDER RE-EXPORTS
+
+    #[cfg(feature = "render")]
+    pub use honeycomb_render::App;
+}