feat: usage g json (#184)

cli/src/cli/generate/json.rs

@@ -0,0 +1,26 @@
+use crate::cli::generate;
+use crate::Result;
+use miette::IntoDiagnostic;
+use std::path::PathBuf;
+
+/// Outputs a usage spec in json format
+#[derive(clap::Args)]
+#[clap()]
+pub struct Json {
+    /// A usage spec taken in as a file
+    #[clap(short, long)]
+    file: Option<PathBuf>,
+
+    /// raw string spec input
+    #[clap(long, required_unless_present = "file", overrides_with = "file")]
+    spec: Option<String>,
+}
+
+impl Json {
+    pub fn run(&self) -> Result<()> {
+        let spec = generate::file_or_spec(&self.file, &self.spec)?;
+        let json = serde_json::to_string_pretty(&spec).into_diagnostic()?;
+        println!("{json}");
+        Ok(())
+    }
+}

cli/src/cli/generate/mod.rs

@@ -5,6 +5,7 @@ use usage::Spec;
 
 mod completion;
 mod fig;
+mod json;
 mod markdown;
 
 #[derive(clap::Args)]
@@ -18,15 +19,17 @@ pub struct Generate {
 pub enum Command {
     Completion(completion::Completion),
     Fig(fig::Fig),
+    Json(json::Json),
     Markdown(markdown::Markdown),
 }
 
 impl Generate {
     pub fn run(&self) -> miette::Result<()> {
         match &self.command {
             Command::Completion(cmd) => cmd.run(),
-            Command::Markdown(cmd) => cmd.run(),
             Command::Fig(cmd) => cmd.run(),
+            Command::Json(cmd) => cmd.run(),
+            Command::Markdown(cmd) => cmd.run(),
         }
     }
 }

cli/usage.usage.kdl

@@ -68,6 +68,14 @@ cmd "generate" subcommand_required=true {
             arg "<OUT_FILE>"
         }
     }
+    cmd "json" help="Outputs a usage spec in json format" {
+        flag "-f --file" help="A usage spec taken in as a file" {
+            arg "<FILE>"
+        }
+        flag "--spec" help="raw string spec input" {
+            arg "<SPEC>"
+        }
+    }
     cmd "markdown" {
         alias "md"
         flag "-f --file" help="A usage spec taken in as a file" required=true {

docs/.vitepress/config.mts

@@ -1,4 +1,17 @@
 import { defineConfig } from "vitepress";
+import spec from "../cli/reference/commands.json";
+
+function getCommands(cmd): string[][] {
+  const commands = [];
+  for (const [name, sub] of Object.entries(cmd.subcommands)) {
+    if (sub.hide) continue;
+    commands.push(sub.full_cmd);
+    commands.push(...getCommands(sub));
+  }
+  return commands;
+}
+
+const commands = getCommands(spec.cmd);
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -31,7 +44,13 @@ export default defineConfig({
           { text: "Manpages", link: "/cli/manpages" },
           { text: "Markdown", link: "/cli/markdown" },
           { text: "Scripts", link: "/cli/scripts" },
-          { text: "CLI Reference", link: "/cli/reference" }
+          {
+            text: "CLI Reference", link: "/cli/reference/", items:
+              commands.map((command) => ({
+                text: command.join(" "),
+                link: `/cli/reference/${command.join("/")}`
+              }))
+          }
         ]
       },
       {

docs/cli/bash.md

@@ -0,0 +1,26 @@
+# `usage bash`
+
+- **Usage**: `usage bash [-h] [--help] <SCRIPT> [ARGS]...`
+- **Source code**: [`cli/src/cli/bash.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/bash.rs)
+
+Executes a bash script
+
+Typically, this will be called by a script's shebang
+
+## Arguments
+
+### `<SCRIPT>`
+
+### `[ARGS]...`
+
+arguments to pass to script
+
+## Flags
+
+### `-h`
+
+show help
+
+### `--help`
+
+show help

docs/cli/complete-word.md

@@ -0,0 +1,33 @@
+# `usage complete-word`
+
+- **Usage**: `usage complete-word [FLAGS] [WORDS]...`
+- **Aliases**: `cw`
+- **Source code**: [`cli/src/cli/complete-word.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/complete-word.rs)
+
+## Arguments
+
+### `[WORDS]...`
+
+user's input from the command line
+
+## Flags
+
+### `--shell <SHELL>`
+
+**Choices:**
+
+- `bash`
+- `fish`
+- `zsh`
+
+### `-f --file <FILE>`
+
+usage spec file or script with usage shebang
+
+### `-s --spec <SPEC>`
+
+raw string spec input
+
+### `--cword <CWORD>`
+
+current word index

docs/cli/generate.md

@@ -0,0 +1,12 @@
+# `usage generate`
+
+- **Usage**: `usage generate <SUBCOMMAND>`
+- **Aliases**: `g`
+- **Source code**: [`cli/src/cli/generate.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate.rs)
+
+## Subcommands
+
+- [`usage generate completion [FLAGS] <SHELL> <BIN>`](/generate/completion.md)
+- [`usage generate fig [FLAGS]`](/generate/fig.md)
+- [`usage generate json [-f --file <FILE>] [--spec <SPEC>]`](/generate/json.md)
+- [`usage generate markdown <FLAGS>`](/generate/markdown.md)

docs/cli/generate/completion.md

@@ -0,0 +1,33 @@
+# `usage generate completion`
+
+- **Usage**: `usage generate completion [FLAGS] <SHELL> <BIN>`
+- **Aliases**: `c`
+- **Source code**: [`cli/src/cli/generate/completion.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/completion.rs)
+
+## Arguments
+
+### `<SHELL>`
+
+**Choices:**
+
+- `bash`
+- `fish`
+- `zsh`
+
+### `<BIN>`
+
+The CLI which we're generates completions for
+
+## Flags
+
+### `--cache-key <CACHE_KEY>`
+
+A cache key to use for storing the results of calling the CLI with --usage-cmd
+
+### `-f --file <FILE>`
+
+A .usage.kdl spec file to use for generating completions
+
+### `--usage-cmd <USAGE_CMD>`
+
+A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to "$bin --usage"

docs/cli/generate/fig.md

@@ -0,0 +1,18 @@
+# `usage generate fig`
+
+- **Usage**: `usage generate fig [FLAGS]`
+- **Source code**: [`cli/src/cli/generate/fig.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/fig.rs)
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `--spec <SPEC>`
+
+raw string spec input
+
+### `--out-file <OUT_FILE>`
+
+File on where to save the generated Fig spec

docs/cli/generate/json.md

@@ -0,0 +1,16 @@
+# `usage generate json`
+
+- **Usage**: `usage generate json [-f --file <FILE>] [--spec <SPEC>]`
+- **Source code**: [`cli/src/cli/generate/json.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/json.rs)
+
+Outputs a usage spec in json format
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `--spec <SPEC>`
+
+raw string spec input

docs/cli/generate/markdown.md

@@ -0,0 +1,29 @@
+# `usage generate markdown`
+
+- **Usage**: `usage generate markdown <FLAGS>`
+- **Aliases**: `md`
+- **Source code**: [`cli/src/cli/generate/markdown.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/markdown.rs)
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `-m --multi`
+
+Render each subcommand as a separate markdown file
+
+### `--url-prefix <URL_PREFIX>`
+
+Prefix to add to all URLs
+
+### `--html-encode`
+
+Escape HTML in markdown
+
+### `--out-dir <OUT_DIR>`
+
+Output markdown files to this directory
+
+### `--out-file <OUT_FILE>`