doc: enable nightly feature doc_auto_cfg for doc generation (#66)

* feat: add rustversion dep & core build script

* feat: add doc_auto_cfg feature when compiling using nightly

* doc: remove feature warning blocks

* ci: update doc CI to use the nightly toolchain

Author: imrn99

.github/workflows/doc.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           submodules: recursive
       # Need to refine this by specifying components required for doc
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@nightly
       - uses: peaceiris/actions-mdbook@v1
         with:
           mdbook-version: "0.4.36"
@@ -30,7 +30,7 @@ jobs:
       - name: Generate User Guide
         run: mdbook build -d ../target/doc/ honeycomb-guide/
       - name: Generate Rust Docs
-        run: cargo doc --all --no-deps --features utils
+        run: cargo +nightly doc --all --no-deps --features utils
 
       - name: Deploy Docs
         uses: peaceiris/actions-gh-pages@v3

Cargo.toml

@@ -29,6 +29,7 @@ honeycomb-render = { version = "0.2.1", path = "./honeycomb-render" }
 
 # common
 cfg-if = "1"
+rustversion = "1.0.15"
 
 # core
 num = "0.4.2"

honeycomb-core/Cargo.toml

@@ -19,3 +19,6 @@ single_precision = []
 [dependencies]
 cfg-if.workspace = true
 num.workspace = true
+
+[build-dependencies]
+rustversion.workspace = true

honeycomb-core/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-core/src/lib.rs

@@ -18,6 +18,8 @@
 
 // ------ CUSTOM LINTS
 
+// --- enable doc_auto_cfg feature if compiling in nightly
+#![cfg_attr(nightly, feature(doc_auto_cfg))]
 // --- some though love for the code
 #![warn(missing_docs)]
 #![warn(clippy::pedantic)]

honeycomb-core/src/utils/generation.rs

@@ -1,11 +1,5 @@
 //! Utility for sample map generation
 //!
-//! <div class="warning">
-//!
-//! **This code is only compiled if the `utils` feature is enabled.**
-//!
-//! </div>
-//!
 //! This module contains code used for sample map / mesh generation. This is mostly
 //! for testing and benchmarking, but could also be hijacked for very (topologically)
 //! simple mesh generation, hence this being kept public.

honeycomb-core/src/utils/mod.rs

@@ -1,11 +1,5 @@
 //! Utility functions & implementations
 //!
-//! <div class="warning">
-//!
-//! **This code is only compiled if the `utils` feature is enabled.**
-//!
-//! </div>
-//!
 //! This module implements basic utilities used for tests & benchmarking
 //! of the structures & methods implemented in `honeycomb_core`.