Add man page generation to release workflow

.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      CARGO_TERM_COLOR: always
+      BUILD_PROFILE: release
+    steps:
+      - uses: actions/checkout@v5
+      - name: Setup Rust
+        uses: leynos/shared-actions/.github/actions/setup-rust@c6559452842af6a83b83429129dccaf910e34562
+      - name: Build
+        run: make release
+      - name: Upload release assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            target/generated-man/wireframe.1

Cargo.toml

@@ -38,6 +38,7 @@ metrics = { version = "0.24.2", optional = true }
 metrics-exporter-prometheus = { version = "0.17.2", optional = true, features = ["http-listener"] }
 thiserror = "2.0.16"
 static_assertions = "1"
+clap = { version = "4.5", features = ["derive"] }
 
 [dev-dependencies]
 rstest = "0.26.1"
@@ -63,6 +64,10 @@ tokio = { version = "1.47.1", default-features = false, features = [
     "test-util",
 ] }
 
+[build-dependencies]
+clap = { version = "4.5", features = ["derive"] }
+clap_mangen = "0.2"
+
 [features]
 default = ["metrics"]
 metrics = ["dep:metrics", "dep:metrics-exporter-prometheus"]

build.rs

@@ -0,0 +1,24 @@
+//! Build script generating manual pages from the CLI definition.
+
+use std::{fs, path::PathBuf};
+
+use clap::CommandFactory;
+use clap_mangen::Man;
+
+#[path = "src/cli.rs"]
+mod cli;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    println!("cargo:rerun-if-changed=src/cli.rs");
+
+    let out_dir = PathBuf::from("target/generated-man");
+    fs::create_dir_all(&out_dir)?;
+
+    let cmd = cli::Cli::command();
+    let man = Man::new(cmd);
+    let mut buf: Vec<u8> = Vec::new();
+    man.render(&mut buf)?;
+    fs::write(out_dir.join("wireframe.1"), buf)?;
+
+    Ok(())
+}

docs/cli.md

@@ -0,0 +1,9 @@
+# Command line interface
+
+Wireframe includes a small command line interface for demonstration. The CLI
+uses `clap` to parse arguments. An optional `--name` flag allows customising
+the greeting printed by the `wireframe` binary.
+
+Manual pages are generated during the build via `clap_mangen`. The `build.rs`
+script writes `wireframe.1` to `target/generated-man`, and the `release` GitHub
+workflow uploads this file.

docs/contents.md

@@ -61,3 +61,5 @@ the-road-to-wireframe-1-0-feature-set-philosophy-and-capability-maturity.md
   writing project documentation.
 - [Server configuration](server/configuration.md) Tuning accept loop backoff
   behaviour and builder options.
+- [Command line interface](cli.md) Overview of CLI usage and man page
+  generation.

src/cli.rs

@@ -0,0 +1,28 @@
+//! Command line interface for the wireframe example binary.
+//!
+//! Provides a tiny CLI to demonstrate argument parsing and man page
+//! generation.
+
+use clap::Parser;
+
+/// Command line arguments for the `wireframe` binary.
+#[derive(Debug, Parser)]
+#[command(name = "wireframe", version, about = "Example Wireframe binary")]
+pub struct Cli {
+    /// Name to greet.
+    #[arg(short, long)]
+    pub name: Option<String>,
+}
+
+#[cfg(test)]
+mod tests {
+    use clap::Parser;
+
+    use super::Cli;
+
+    #[test]
+    fn parses_name_option() {
+        let cli = Cli::parse_from(["wireframe", "--name", "Sam"]);
+        assert_eq!(cli.name.as_deref(), Some("Sam"));
+    }
+}

src/main.rs

@@ -1,10 +1,20 @@
 //! Minimal binary demonstrating `wireframe` usage.
 //!
-//! Currently prints a greeting and exits.
+//! Parses CLI arguments and prints a greeting.
+
+mod cli;
+
+use clap::Parser;
 
 fn main() {
     // Enable structured logging for examples and integration tests.
     // Applications embedding the library should install their own subscriber.
     tracing_subscriber::fmt::init();
-    println!("Hello from Wireframe!");
+
+    let cli = cli::Cli::parse();
+    if let Some(name) = cli.name {
+        println!("Hello, {name} from Wireframe!");
+    } else {
+        println!("Hello from Wireframe!");
+    }
 }