Use clap-markdown to produce usage in a markdown file. (WIP)

Cargo.toml

@@ -71,6 +71,7 @@ name = "weaver"
 
 [dependencies]
 # local crates dependencies
+weaver_cli = { path = "crates/weaver_cli" }
 weaver_common = { path = "crates/weaver_common" }
 weaver_resolver = { path = "crates/weaver_resolver" }
 weaver_semconv = { path = "crates/weaver_semconv" }
@@ -82,7 +83,7 @@ weaver_emit = { path = "crates/weaver_emit" }
 weaver_live_check = { path = "crates/weaver_live_check" }
 
 clap = { version = "4.5.37", features = ["derive"] }
-clap_complete = "4.5.47"
+clap_complete = "4.5.48"
 rayon = "1.10.0"
 ratatui = { version = "0.29.0", features = ["serde"] }
 tui-textarea = "0.7.0"
@@ -256,3 +257,4 @@ github-custom-runners = { global="ubuntu-latest", x86_64-unknown-linux-gnu="ubun
 #todo = "warn"
 #implicit_clone = "warn"
 #inconsistent_struct_constructor = "warn"
+

crates/weaver_cli/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "weaver_cli"
+version.workspace = true
+authors.workspace = true
+repository.workspace = true
+license.workspace = true
+publish.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+clap = { version = "4.5.37", features = ["derive"] }
+clap_complete = "4.5.50"
+#serde_yaml = "0.9.34"
+weaver_common = { path = "../weaver_common" }
+weaver_emit = { path = "../weaver_emit" }
+serde_yaml = "0.9.34+deprecated"
+thiserror = "1.0.69"
+serde = { version = "1.0.219", features = ["derive"] }
+miette = { version = "7.5.0", features = ["fancy", "serde"] }
+
+[lints]
+workspace = true

crates/weaver_cli/README.md

@@ -0,0 +1,4 @@
+# Weaver CLI
+
+This crate is used to isolate the CLI code from the rest of the weaver codebase. This is so we can generate the markdown
+help, as well as the man page file without having to build that into the weaver binary.

crates/weaver_cli/allowed-external-types.toml

@@ -0,0 +1,7 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+# This is used with cargo-check-external-types to reduce the surface area of downstream crates from
+# the public API. Ideally this can have a few exceptions as possible.
+allowed_external_types = [
+
+]

src/cli.rs → crates/weaver_cli/src/cli.rs

@@ -6,15 +6,16 @@ use crate::diagnostic::DiagnosticCommand;
 use crate::registry::RegistryCommand;
 use clap::{Args, Parser, Subcommand};
 
-/// Command line arguments.
+/// Manage semantic convention registry and telemetry schema workflows (OpenTelemetry Project)
 #[derive(Parser)]
 #[command(
     author,
     version,
     about,
     long_about = None,
     subcommand_required = true,
-    arg_required_else_help = true
+    arg_required_else_help = true,
+    bin_name = "weaver"
 )]
 pub struct Cli {
     /// Turn debugging information on
@@ -48,13 +49,14 @@ pub enum Commands {
     Completion(CompletionCommand),
 }
 
+/// Commands for generating completions and markdown documentation
 #[derive(Args)]
 pub struct CompletionCommand {
     /// The shell to generate the completions for
     #[arg(value_enum)]
     pub shell: clap_complete::Shell,
 
-    /// (Optional) The file to write the completions to. Defaults to STDOUT.
+    /// (Optional) The file to write the completions to. Defaults to `STDOUT`.
     #[arg(long, hide = true)]
     pub completion_file: Option<std::path::PathBuf>,
 }

crates/weaver_cli/src/diagnostic/init.rs

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Module for diagnostic init sub-command.
+
+use crate::DiagnosticArgs;
+use clap::Args;
+use std::path::PathBuf;
+
+/// Parameters for the `diagnostic init` sub-command
+#[derive(Debug, Args)]
+pub struct DiagnosticInitArgs {
+    /// Optional target to initialize the diagnostic templates for. If empty, all default templates will be extracted.
+    #[arg(default_value = "")]
+    pub target: String,
+
+    /// Optional path where the diagnostic templates directory should be created.
+    #[arg(short = 't', long, default_value = "diagnostic_templates")]
+    pub diagnostic_templates_dir: PathBuf,
+
+    /// Parameters to specify the diagnostic format.
+    #[command(flatten)]
+    pub diagnostic: DiagnosticArgs,
+}

crates/weaver_cli/src/diagnostic/mod.rs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! The weaver CLI diagnostic command module
+
+pub mod init;
+
+use clap::{Args, Subcommand};
+
+/// Parameters for the `diagnostic` command
+#[derive(Debug, Args)]
+pub struct DiagnosticCommand {
+    /// Define the sub-commands for the `diagnostic` command
+    #[clap(subcommand)]
+    pub command: DiagnosticSubCommand,
+}
+
+/// Sub-commands to manage `diagnostic` messages.
+#[derive(Debug, Subcommand)]
+#[clap(verbatim_doc_comment)]
+pub enum DiagnosticSubCommand {
+    /// Initializes a `diagnostic_templates` directory to define or override diagnostic output
+    /// formats.
+    Init(init::DiagnosticInitArgs),
+}

crates/weaver_cli/src/format.rs

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Supported output formats for the resolved registry and telemetry schema
+
+use clap::ValueEnum;
+
+/// Supported output formats for the resolved schema
+#[derive(Debug, Clone, ValueEnum)]
+pub enum Format {
+    /// YAML format
+    Yaml,
+    /// JSON format
+    Json,
+}

crates/weaver_cli/src/lib.rs

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Weaver command and subcommands
+
+use clap::Args;
+use std::path::PathBuf;
+
+pub mod cli;
+pub mod diagnostic;
+pub mod format;
+pub mod registry;
+
+/// Set of parameters used to specify the diagnostic format.
+#[derive(Args, Debug, Clone)]
+pub struct DiagnosticArgs {
+    /// Format used to render the diagnostic messages. Predefined formats are: `ansi`, `json`,
+    /// `gh_workflow_command`.
+    #[arg(long, default_value = "ansi")]
+    pub diagnostic_format: String,
+
+    /// Path to the directory where the diagnostic templates are located.
+    #[arg(long, default_value = "diagnostic_templates")]
+    pub diagnostic_template: PathBuf,
+
+    /// Send the output to stdout instead of stderr.
+    #[arg(long)]
+    pub diagnostic_stdout: bool,
+}
+
+impl Default for DiagnosticArgs {
+    fn default() -> Self {
+        Self {
+            diagnostic_format: "ansi".to_owned(),
+            diagnostic_template: PathBuf::from("diagnostic_templates"),
+            diagnostic_stdout: false,
+        }
+    }
+}

crates/weaver_cli/src/registry/check.rs

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Weaver registry check sub-command.
+
+use crate::registry::{PolicyArgs, RegistryArgs};
+use crate::DiagnosticArgs;
+use clap::Args;
+use weaver_common::vdir::VirtualDirectoryPath;
+
+/// Parameters for the `registry check` sub-command
+#[derive(Debug, Args)]
+pub struct RegistryCheckArgs {
+    /// Parameters to specify the semantic convention registry
+    #[command(flatten)]
+    pub registry: RegistryArgs,
+
+    /// Parameters to specify the baseline semantic convention registry
+    #[arg(long)]
+    pub baseline_registry: Option<VirtualDirectoryPath>,
+
+    /// Policy parameters
+    #[command(flatten)]
+    pub policy: PolicyArgs,
+
+    /// Parameters to specify the diagnostic format.
+    #[command(flatten)]
+    pub diagnostic: DiagnosticArgs,
+}

crates/weaver_cli/src/registry/diff.rs

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Weaver registry diff sub-command.
+
+use crate::registry::RegistryArgs;
+use crate::DiagnosticArgs;
+use clap::Args;
+use std::path::PathBuf;
+use weaver_common::vdir::VirtualDirectoryPath;
+
+/// Parameters for the `registry diff` sub-command
+#[derive(Debug, Args)]
+pub struct RegistryDiffArgs {
+    /// Parameters to specify the semantic convention registry
+    #[command(flatten)]
+    pub registry: RegistryArgs,
+
+    /// Parameters to specify the baseline semantic convention registry
+    #[arg(long)]
+    pub baseline_registry: VirtualDirectoryPath,
+
+    /// Format used to render the schema changes. Predefined formats are: `ansi`, `json`,
+    /// and `markdown`.
+    #[arg(long, default_value = "ansi")]
+    pub diff_format: String,
+
+    /// Path to the directory where the schema changes templates are located.
+    #[arg(long, default_value = "diff_templates")]
+    pub diff_template: PathBuf,
+
+    /// Path to the directory where the generated artifacts will be saved.
+    /// If not specified, the diff report is printed to stdout
+    #[arg(short, long)]
+    pub output: Option<PathBuf>,
+
+    /// Parameters to specify the diagnostic format.
+    #[command(flatten)]
+    pub diagnostic: DiagnosticArgs,
+}

crates/weaver_cli/src/registry/emit.rs

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Weaver registry emit sub-command.
+
+use crate::registry::{PolicyArgs, RegistryArgs};
+use crate::DiagnosticArgs;
+use clap::Args;
+
+/// Parameters for the `registry emit` sub-command
+#[derive(Debug, Args)]
+pub struct RegistryEmitArgs {
+    /// Parameters to specify the semantic convention registry
+    #[command(flatten)]
+    pub registry: RegistryArgs,
+
+    /// Policy parameters
+    #[command(flatten)]
+    pub policy: PolicyArgs,
+
+    /// Parameters to specify the diagnostic format.
+    #[command(flatten)]
+    pub diagnostic: DiagnosticArgs,
+
+    /// Write the telemetry to standard output
+    #[arg(long)]
+    pub stdout: bool,
+
+    /// Endpoint for the OTLP receiver. OTEL_EXPORTER_OTLP_ENDPOINT env var will override this.
+    #[arg(long, default_value = weaver_emit::DEFAULT_OTLP_ENDPOINT)]
+    pub endpoint: String,
+}