[xtask] Add support for xtask doc commands

build/xtask/src/main.rs

@@ -11,7 +11,6 @@ use crate::config::Config;
 
 mod auxflash;
 mod caboose_pos;
-mod clippy;
 mod config;
 mod dist;
 mod elf;
@@ -20,6 +19,7 @@ mod gha_prepare_artifacts;
 mod graph;
 mod humility;
 mod lsp;
+mod passthrough;
 mod print;
 mod sizes;
 mod task_slot;
@@ -156,6 +156,24 @@ enum Xtask {
         caboose_args: CabooseArgs,
     },
 
+    /// Runs `cargo doc` on a specified task
+    Doc {
+        /// Request verbosity from tools we shell out to.
+        #[clap(short)]
+        verbose: bool,
+
+        /// Path to the image configuration file, in TOML.
+        cfg: PathBuf,
+
+        /// Name of task(s) to check.
+        tasks: Vec<String>,
+
+        /// Arguments passed directly to the `cargo doc` invocation,
+        /// e.g. `--open`
+        #[clap(last = true)]
+        doc_args: Vec<String>,
+    },
+
     /// Runs `cargo clippy` on a specified task
     Clippy {
         /// Request verbosity from tools we shell out to.
@@ -489,7 +507,26 @@ fn run(xtask: Xtask) -> Result<()> {
             tasks,
             extra_options,
         } => {
-            clippy::run(verbose, cfg, &tasks, &extra_options)?;
+            // Clippy commands are passed AFTER the `--`, currently pre-options
+            // are not supported.
+            passthrough::run(
+                "clippy",
+                verbose,
+                cfg,
+                &tasks,
+                &[],
+                &extra_options,
+            )?;
+        }
+        Xtask::Doc {
+            verbose,
+            cfg,
+            tasks,
+            doc_args,
+        } => {
+            // Doc commands are passed BEFORE the `--`, currently post-options
+            // are not supported.
+            passthrough::run("doc", verbose, cfg, &tasks, &doc_args, &[])?;
         }
         Xtask::TaskSlots { task_bin } => {
             task_slot::dump_task_slot_table(&task_bin)?;

build/xtask/src/clippy.rs → build/xtask/src/passthrough.rs

@@ -8,11 +8,27 @@ use anyhow::{Result, bail};
 
 use crate::config::Config;
 
+/// A passthrough function for plumbing basic `cargo ...` commands in the
+/// context of a hubris build.
+///
+/// ## Arguments
+///
+/// * `cargo_cmd`: The cargo subcommand, e.g. `doc` or `clippy`
+/// * `verbose`: Toggles verbosity
+/// * `cfg`: Path to the `app.toml`
+/// * `tasks`: List of task names to run this command on, will run cargo
+///   subcommand on EACH specified task
+/// * `direct_opts`: Arguments to be passed BEFORE the `--` of the command
+///   invocation, e.g. `cargo subcommand $DIRECT_OPTS`
+/// * `post_opts`: Arguments to be passed AFTER the `--` of the command
+///   invocation, e.g. `cargo subcommand -- $POST_OPTS`
 pub fn run(
+    cargo_cmd: &str,
     verbose: bool,
     cfg: PathBuf,
     tasks: &[String],
-    options: &[String],
+    direct_opts: &[String],
+    post_opts: &[String],
 ) -> Result<()> {
     let toml = Config::from_file(&cfg)?;
 
@@ -112,17 +128,21 @@ pub fn run(
         } else {
             toml.task_build_config(name, verbose, None).unwrap()
         };
-        let mut cmd = build_config.cmd("clippy");
+        let mut cmd = build_config.cmd(cargo_cmd);
+
+        for opt in direct_opts {
+            cmd.arg(opt);
+        }
 
         cmd.arg("--");
 
-        for opt in options {
+        for opt in post_opts {
             cmd.arg(opt);
         }
 
         let status = cmd.status()?;
         if !status.success() {
-            bail!("`cargo clippy` failed, see output for details");
+            bail!("`cargo {cargo_cmd}` failed, see output for details");
         }
     }
     Ok(())