Switch to hand-written man pages with auto option sync

See the updates to `Justfile` for how to use this.

Closes: #1428

Assisted-By: Claude Code (opus + sonnet)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Run tests
         run: cargo test -- --nocapture --quiet
       - name: Manpage generation
-        run: mkdir -p target/man && cargo run --features=docgen -- man --directory target/man
+        run: cargo xtask update-generated
       - name: Clippy (gate on correctness and suspicous)
         run: make validate-rust
   fedora-container-tests:

Cargo.lock

@@ -16,3 +16,14 @@ run-container-external-tests:
 
 unittest *ARGS:
     podman build --jobs=4 --target units -t localhost/bootc-units --build-arg=unitargs={{ARGS}} .
+
+# Update all generated files (man pages and JSON schemas)
+#
+# This is the unified command that:
+# - Auto-discovers new CLI commands and creates man page templates
+# - Syncs CLI options from Rust code to existing man page templates  
+# - Updates JSON schema files
+#
+# Use this after adding, removing, or modifying CLI options or schemas.
+update-generated:
+    cargo run -p xtask update-generated

Justfile

@@ -279,14 +279,6 @@ pub(crate) enum InstallOpts {
     PrintConfiguration,
 }
 
-/// Options for man page generation
-#[derive(Debug, Parser, PartialEq, Eq)]
-pub(crate) struct ManOpts {
-    #[clap(long)]
-    /// Output to this directory
-    pub(crate) directory: Utf8PathBuf,
-}
-
 /// Subcommands which can be executed as part of a container build.
 #[derive(Debug, clap::Subcommand, PartialEq, Eq)]
 pub(crate) enum ContainerOpts {
@@ -540,6 +532,9 @@ pub(crate) enum InternalsOpts {
         #[clap(long)]
         merge: bool,
     },
+    #[cfg(feature = "docgen")]
+    /// Dump CLI structure as JSON for documentation generation
+    DumpCliJson,
 }
 
 #[derive(Debug, clap::Subcommand, PartialEq, Eq)]
@@ -704,9 +699,6 @@ pub(crate) enum Opt {
     #[clap(subcommand)]
     #[clap(hide = true)]
     Internals(InternalsOpts),
-    #[clap(hide(true))]
-    #[cfg(feature = "docgen")]
-    Man(ManOpts),
 }
 
 /// Ensure we've entered a mount namespace, so that we can remount
@@ -1500,6 +1492,14 @@ async fn run_from_opt(opt: Opt) -> Result<()> {
             }
             #[cfg(feature = "rhsm")]
             InternalsOpts::PublishRhsmFacts => crate::rhsm::publish_facts(&root).await,
+            #[cfg(feature = "docgen")]
+            InternalsOpts::DumpCliJson => {
+                use clap::CommandFactory;
+                let cmd = Opt::command();
+                let json = crate::cli_json::dump_cli_json(&cmd)?;
+                println!("{}", json);
+                Ok(())
+            }
             InternalsOpts::DirDiff {
                 pristine_etc,
                 current_etc,
@@ -1523,8 +1523,6 @@ async fn run_from_opt(opt: Opt) -> Result<()> {
                 Ok(())
             }
         },
-        #[cfg(feature = "docgen")]
-        Opt::Man(manopts) => crate::docgen::generate_manpages(&manopts.directory),
         Opt::State(opts) => match opts {
             StateOpts::WipeOstree => {
                 let sysroot = ostree::Sysroot::new_default();

crates/lib/src/cli.rs

@@ -0,0 +1,127 @@
+//! Export CLI structure as JSON for documentation generation
+
+use clap::Command;
+use serde::{Deserialize, Serialize};
+
+/// Representation of a CLI option for JSON export
+#[derive(Debug, Serialize, Deserialize)]
+pub struct CliOption {
+    pub long: String,
+    pub short: Option<String>,
+    pub value_name: Option<String>,
+    pub default: Option<String>,
+    pub help: String,
+    pub possible_values: Vec<String>,
+    pub required: bool,
+}
+
+/// Representation of a CLI command for JSON export
+#[derive(Debug, Serialize, Deserialize)]
+pub struct CliCommand {
+    pub name: String,
+    pub about: Option<String>,
+    pub options: Vec<CliOption>,
+    pub positionals: Vec<CliPositional>,
+    pub subcommands: Vec<CliCommand>,
+}
+
+/// Representation of a positional argument
+#[derive(Debug, Serialize, Deserialize)]
+pub struct CliPositional {
+    pub name: String,
+    pub help: Option<String>,
+    pub required: bool,
+    pub multiple: bool,
+}
+
+/// Convert a clap Command to our JSON representation
+pub fn command_to_json(cmd: &Command) -> CliCommand {
+    let mut options = Vec::new();
+    let mut positionals = Vec::new();
+
+    // Extract arguments
+    for arg in cmd.get_arguments() {
+        let id = arg.get_id().as_str();
+
+        // Skip built-in help and version
+        if id == "help" || id == "version" {
+            continue;
+        }
+
+        // Skip hidden arguments
+        if arg.is_hide_set() {
+            continue;
+        }
+
+        if arg.is_positional() {
+            // Handle positional arguments
+            positionals.push(CliPositional {
+                name: id.to_string(),
+                help: arg.get_help().map(|h| h.to_string()),
+                required: arg.is_required_set(),
+                multiple: false, // For now, simplify this
+            });
+        } else {
+            // Handle options/flags
+            let mut possible_values = Vec::new();
+            let pvs = arg.get_possible_values();
+            if !pvs.is_empty() {
+                for pv in pvs {
+                    possible_values.push(pv.get_name().to_string());
+                }
+            }
+
+            let help = arg.get_help().map(|h| h.to_string()).unwrap_or_default();
+
+            options.push(CliOption {
+                long: arg
+                    .get_long()
+                    .map(String::from)
+                    .unwrap_or_else(|| id.to_string()),
+                short: arg.get_short().map(|c| c.to_string()),
+                value_name: arg
+                    .get_value_names()
+                    .and_then(|names| names.first())
+                    .map(|s| s.to_string()),
+                default: arg
+                    .get_default_values()
+                    .first()
+                    .and_then(|v| v.to_str())
+                    .map(String::from),
+                help,
+                possible_values,
+                required: arg.is_required_set(),
+            });
+        }
+    }
+
+    // Extract subcommands
+    let mut subcommands = Vec::new();
+    for subcmd in cmd.get_subcommands() {
+        // Skip help subcommand
+        if subcmd.get_name() == "help" {
+            continue;
+        }
+
+        // Skip hidden subcommands
+        if subcmd.is_hide_set() {
+            continue;
+        }
+
+        subcommands.push(command_to_json(subcmd));
+    }
+
+    CliCommand {
+        name: cmd.get_name().to_string(),
+        about: cmd.get_about().map(|s| s.to_string()),
+        options,
+        positionals,
+        subcommands,
+    }
+}
+
+/// Dump the entire CLI structure as JSON
+pub fn dump_cli_json(cmd: &Command) -> Result<String, serde_json::Error> {
+    let cli_structure = command_to_json(cmd);
+    serde_json::to_string_pretty(&cli_structure)
+}

crates/lib/src/cli_json.rs

@@ -29,7 +29,7 @@ mod task;
 mod utils;
 
 #[cfg(feature = "docgen")]
-mod docgen;
+mod cli_json;
 
 mod bootloader;
 mod containerenv;

crates/lib/src/docgen.rs

@@ -17,6 +17,8 @@ anyhow = { workspace = true }
 camino = { workspace = true }
 chrono = { workspace = true, features = ["std"] }
 fn-error-context = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
 tempfile = { workspace = true }
 toml = { workspace = true }
 xshell = { workspace = true }