Generate CLI reference

Signed-off-by: itowlson <[email protected]>

Author: itowlson

Cargo.lock

@@ -19,6 +19,7 @@ anyhow = { workspace = true }
 async-trait = { workspace = true }
 bytes = { workspace = true }
 clap = { version = "3.2.24", features = ["derive", "env"] }
+clap-markdown = { git = "https://github.com/itowlson/clap-markdown", rev = "9e484a05ac70bfb928453559fa45a49534dac121" }
 clearscreen = "3"
 comfy-table = "7"
 command-group = "2"

Cargo.toml

@@ -2,6 +2,7 @@ use anyhow::{Context, Error};
 use clap::{CommandFactory, FromArgMatches, Parser, Subcommand};
 use lazy_static::lazy_static;
 use spin_cli::commands::external::predefined_externals;
+use spin_cli::commands::maintenance::MaintenanceCommands;
 use spin_cli::commands::{
     build::BuildCommand,
     cloud::{DeployCommand, LoginCommand},
@@ -135,6 +136,8 @@ enum SpinApp {
     #[clap(alias = "w")]
     Watch(WatchCommand),
     Doctor(DoctorCommand),
+    #[clap(subcommand, hide = true)]
+    Maintenance(MaintenanceCommands),
 }
 
 #[derive(Subcommand)]
@@ -164,6 +167,7 @@ impl SpinApp {
             Self::External(cmd) => execute_external_subcommand(cmd, app).await,
             Self::Watch(cmd) => cmd.run().await,
             Self::Doctor(cmd) => cmd.run().await,
+            Self::Maintenance(cmd) => cmd.run(SpinApp::command()).await,
         }
     }
 }

src/bin/spin.rs

@@ -8,6 +8,8 @@ pub mod cloud;
 pub mod doctor;
 /// Commands for external subcommands (i.e. plugins)
 pub mod external;
+/// Commands for Spin maintenance tasks.
+pub mod maintenance;
 /// Command for creating a new application.
 pub mod new;
 /// Command for adding a plugin to Spin

src/commands.rs

@@ -0,0 +1,36 @@
+use std::path::PathBuf;
+
+use clap::{Parser, Subcommand};
+
+/// Commands for Spin maintenance tasks.
+#[derive(Subcommand, Debug)]
+pub enum MaintenanceCommands {
+    /// Generate CLI reference docs in Markdown format.
+    GenerateReference(GenerateReference),
+}
+
+impl MaintenanceCommands {
+    pub async fn run(&self, app: clap::Command<'_>) -> anyhow::Result<()> {
+        match self {
+            MaintenanceCommands::GenerateReference(g) => g.run(app).await,
+        }
+    }
+}
+
+#[derive(Parser, Debug)]
+pub struct GenerateReference {
+    /// The file to which to generate the reference Markdown. If omitted, it is generated to stdout.
+    #[clap(short = 'o')]
+    pub output: Option<PathBuf>,
+}
+
+impl GenerateReference {
+    pub async fn run(&self, app: clap::Command<'_>) -> anyhow::Result<()> {
+        let markdown = clap_markdown::help_markdown_command(&app);
+        match &self.output {
+            Some(path) => std::fs::write(path, markdown)?,
+            None => println!("{markdown}"),
+        }
+        Ok(())
+    }
+}