.github/workflows/docs-and-testcov.yml

@@ -170,8 +170,10 @@ jobs:
 
       - name: Build user guide
         run: |
-          cargo binstall mdbook
-          bash ./docs/build.sh
+          cargo binstall mdbook -q
+          cd docs
+          ./build.sh
+          cd ..
 
       - name: Copy user guide to output directory
         run: |

.github/workflows/run-unit-tests.yml

@@ -81,5 +81,7 @@ jobs:
 
       - name: Test build user guide
         run: |
-          cargo binstall mdbook
-          bash ./docs/build.sh
+          cargo binstall mdbook -q
+          cd docs
+          ./build.sh
+          cd ..

README.md

@@ -198,14 +198,3 @@ To run the benchmarks, use:
 ```bash
 cargo bench --features "bench"
 ```
-
-## Building the user-guide
-
-To build the user guide, use:
-
-```bash
-cargo binstall mdbook
-bash docs/build.sh
-```
-
-This will generate the user guide in the `docs/book` directory.

docs/build.sh

@@ -1,7 +1,15 @@
 #!/usr/bin/env sh
 # Build and test the RustFrame user guide using mdBook.
 set -e
+# Ensure the library is compiled so examples can link against it.
 
-cd docs
-bash gen.sh "$@"
-cd ..
+cargo clean
+
+cargo build --manifest-path ../Cargo.toml
+# Run embedded code examples as tests.
+mdbook test -L ../target/debug/deps "$@"
+# Finally, render the book.
+mdbook build "$@"
+
+cargo build
+cargo build --release

docs/gen.sh

@@ -1,14 +0,0 @@
-#!/usr/bin/env sh
-
-set -e
-
-cargo clean
-
-cargo build --manifest-path ../Cargo.toml
-
-mdbook test -L ../target/debug/deps "$@"
-
-mdbook build "$@"
-
-cargo build
-cargo build --release

docs/src/introduction.md

@@ -4,7 +4,12 @@ Welcome to the **RustFrame User Guide**. This book provides a tour of
 RustFrame's capabilities from basic data handling to advanced machine learning
 workflows. Each chapter contains runnable snippets so you can follow along.
 
+To build this guide locally run `./build.sh` in the `docs/` directory. The
+chapters are arranged sequentially:
+
 1. [Data manipulation](./data-manipulation.md) for loading and transforming data.
 2. [Compute features](./compute.md) for statistics and analytics.
 3. [Machine learning](./machine-learning.md) for predictive models.
 4. [Utilities](./utilities.md) for supporting helpers and upcoming modules.
+
+Let's begin with some tabular data!