wip

jdx · Dec 9, 2024 · 38312d4 · 38312d4
1 parent 31fa1e3
commit 38312d4
Show file tree

Hide file tree

Showing 6 changed files with 316 additions and 25 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -1,4 +1,18 @@
-import { defineConfig } from 'vitepress'
+import { defineConfig } from "vitepress";
+
+import spec from "../cli/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({
@@ -7,22 +21,25 @@ export default defineConfig({
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     nav: [
-      { text: 'Home', link: '/' },
-      { text: 'CLI Reference', link: '/cli' },
+      { text: "Home", link: "/" },
+      { text: "CLI Reference", link: "/cli" },
     ],
 
     sidebar: [
-      { text: 'Getting Started', link: '/getting-started' },
-      { text: 'CLI Reference', link: '/cli' },
+      { text: "Getting Started", link: "/getting-started" },
+      {
+        text: "CLI Reference",
+        link: "/cli",
+        items: commands.map((cmd) => ({
+          text: cmd.join(" "),
+          link: `/cli/${cmd.join("/")}`,
+        })),
+      },
     ],
 
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/jdx/pitchfork' }
-    ],
+    socialLinks: [{ icon: "github", link: "https://github.com/jdx/pitchfork" }],
 
-    logo: '/logo.png',
+    logo: "/logo.png",
   },
-  head: [
-    ['link', { rel: 'icon', href: '/img/favicon.ico' }],
-  ],
-})
+  head: [["link", { rel: "icon", href: "/img/favicon.ico" }]],
+});
diff --git a/docs/cli/commands.json b/docs/cli/commands.json
@@ -0,0 +1,269 @@
+{
+  "name": "pitchfork-cli",
+  "bin": "pitchfork",
+  "cmd": {
+    "full_cmd": [],
+    "usage": "<SUBCOMMAND>",
+    "subcommands": {
+      "daemon": {
+        "full_cmd": [
+          "daemon"
+        ],
+        "usage": "daemon <SUBCOMMAND>",
+        "subcommands": {
+          "run": {
+            "full_cmd": [
+              "daemon",
+              "run"
+            ],
+            "usage": "daemon run [-f --force]",
+            "subcommands": {},
+            "args": [],
+            "flags": [
+              {
+                "name": "force",
+                "usage": "-f --force",
+                "help": "kill existing daemon",
+                "help_first_line": "kill existing daemon",
+                "short": [
+                  "f"
+                ],
+                "long": [
+                  "force"
+                ],
+                "hide": false,
+                "global": false
+              }
+            ],
+            "mounts": [],
+            "hide": false,
+            "help": "Runs the internal pitchfork daemon in the foreground",
+            "name": "run",
+            "aliases": [],
+            "hidden_aliases": [],
+            "examples": []
+          },
+          "start": {
+            "full_cmd": [
+              "daemon",
+              "start"
+            ],
+            "usage": "daemon start [-f --force]",
+            "subcommands": {},
+            "args": [],
+            "flags": [
+              {
+                "name": "force",
+                "usage": "-f --force",
+                "help": "kill existing daemon",
+                "help_first_line": "kill existing daemon",
+                "short": [
+                  "f"
+                ],
+                "long": [
+                  "force"
+                ],
+                "hide": false,
+                "global": false
+              }
+            ],
+            "mounts": [],
+            "hide": false,
+            "help": "Starts the internal pitchfork daemon in the background",
+            "name": "start",
+            "aliases": [],
+            "hidden_aliases": [],
+            "examples": []
+          },
+          "stop": {
+            "full_cmd": [
+              "daemon",
+              "stop"
+            ],
+            "usage": "daemon stop",
+            "subcommands": {},
+            "args": [],
+            "flags": [],
+            "mounts": [],
+            "hide": false,
+            "help": "Stops the internal pitchfork daemon running in the background",
+            "name": "stop",
+            "aliases": [],
+            "hidden_aliases": [],
+            "examples": []
+          }
+        },
+        "args": [],
+        "flags": [],
+        "mounts": [],
+        "hide": false,
+        "subcommand_required": true,
+        "name": "daemon",
+        "aliases": [],
+        "hidden_aliases": [],
+        "examples": []
+      },
+      "logs": {
+        "full_cmd": [
+          "logs"
+        ],
+        "usage": "logs [-n <N>] [-t --tail] [NAME]...",
+        "subcommands": {},
+        "args": [
+          {
+            "name": "NAME",
+            "usage": "[NAME]...",
+            "help": "Show only logs for the specified daemon(s)",
+            "help_first_line": "Show only logs for the specified daemon(s)",
+            "required": false,
+            "var": true,
+            "hide": false
+          }
+        ],
+        "flags": [
+          {
+            "name": "n",
+            "usage": "-n <N>",
+            "help": "Show N lines of logs",
+            "help_long": "Show N lines of logs\n\nSet to 0 to show all logs",
+            "help_first_line": "Show N lines of logs",
+            "short": [
+              "n"
+            ],
+            "long": [],
+            "hide": false,
+            "global": false,
+            "arg": {
+              "name": "N",
+              "usage": "<N>",
+              "required": true,
+              "hide": false
+            }
+          },
+          {
+            "name": "tail",
+            "usage": "-t --tail",
+            "help": "Show logs in real-time",
+            "help_first_line": "Show logs in real-time",
+            "short": [
+              "t"
+            ],
+            "long": [
+              "tail"
+            ],
+            "hide": false,
+            "global": false
+          }
+        ],
+        "mounts": [],
+        "hide": false,
+        "help": "Displays logs for daemon(s)",
+        "name": "logs",
+        "aliases": [],
+        "hidden_aliases": [],
+        "examples": []
+      },
+      "run": {
+        "full_cmd": [
+          "run"
+        ],
+        "usage": "run [-f --force] <NAME> [CMD]...",
+        "subcommands": {},
+        "args": [
+          {
+            "name": "NAME",
+            "usage": "<NAME>",
+            "help": "Name of the daemon to run",
+            "help_first_line": "Name of the daemon to run",
+            "required": true,
+            "hide": false
+          },
+          {
+            "name": "CMD",
+            "usage": "[CMD]...",
+            "required": false,
+            "var": true,
+            "hide": false
+          }
+        ],
+        "flags": [
+          {
+            "name": "force",
+            "usage": "-f --force",
+            "short": [
+              "f"
+            ],
+            "long": [
+              "force"
+            ],
+            "hide": false,
+            "global": false
+          }
+        ],
+        "mounts": [],
+        "hide": false,
+        "help": "Runs a one-off daemon",
+        "name": "run",
+        "aliases": [],
+        "hidden_aliases": [],
+        "examples": []
+      },
+      "start": {
+        "full_cmd": [
+          "start"
+        ],
+        "usage": "start [NAME]...",
+        "subcommands": {},
+        "args": [
+          {
+            "name": "NAME",
+            "usage": "[NAME]...",
+            "help": "Name of the daemon(s) in pitchfork.toml to start",
+            "help_first_line": "Name of the daemon(s) in pitchfork.toml to start",
+            "required": false,
+            "var": true,
+            "hide": false
+          }
+        ],
+        "flags": [],
+        "mounts": [],
+        "hide": false,
+        "help": "Starts a daemon from a pitchfork.toml file",
+        "name": "start",
+        "aliases": [],
+        "hidden_aliases": [],
+        "examples": []
+      },
+      "usage": {
+        "full_cmd": [
+          "usage"
+        ],
+        "usage": "usage",
+        "subcommands": {},
+        "args": [],
+        "flags": [],
+        "mounts": [],
+        "hide": false,
+        "help": "Generates a usage spec for the CLI",
+        "help_long": "Generates a usage spec for the CLI\n\nhttps://usage.jdx.dev",
+        "name": "usage",
+        "aliases": [],
+        "hidden_aliases": [],
+        "examples": []
+      }
+    },
+    "args": [],
+    "flags": [],
+    "mounts": [],
+    "hide": false,
+    "name": "pitchfork",
+    "aliases": [],
+    "hidden_aliases": [],
+    "examples": []
+  },
+  "config": {
+    "props": {}
+  },
+  "usage": "Usage: pitchfork-cli <COMMAND>",
+  "complete": {}
+}
diff --git a/docs/cli/daemon.md b/docs/cli/daemon.md
@@ -4,6 +4,6 @@
 
 ## Subcommands
 
-- [`pitchfork daemon run [-f --force]`](/daemon/run.md)
-- [`pitchfork daemon start [-f --force]`](/daemon/start.md)
-- [`pitchfork daemon stop`](/daemon/stop.md)
+- [`pitchfork daemon run [-f --force]`](/cli/daemon/run.md)
+- [`pitchfork daemon start [-f --force]`](/cli/daemon/start.md)
+- [`pitchfork daemon stop`](/cli/daemon/stop.md)
diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -6,11 +6,11 @@
 
 ## Subcommands
 
-- [`pitchfork daemon <SUBCOMMAND>`](/daemon.md)
-- [`pitchfork daemon run [-f --force]`](/daemon/run.md)
-- [`pitchfork daemon start [-f --force]`](/daemon/start.md)
-- [`pitchfork daemon stop`](/daemon/stop.md)
-- [`pitchfork logs [-n <N>] [-t --tail] [NAME]...`](/logs.md)
-- [`pitchfork run [-f --force] <NAME> [CMD]...`](/run.md)
-- [`pitchfork start [NAME]...`](/start.md)
-- [`pitchfork usage`](/usage.md)
+- [`pitchfork daemon <SUBCOMMAND>`](/cli/daemon.md)
+- [`pitchfork daemon run [-f --force]`](/cli/daemon/run.md)
+- [`pitchfork daemon start [-f --force]`](/cli/daemon/start.md)
+- [`pitchfork daemon stop`](/cli/daemon/stop.md)
+- [`pitchfork logs [-n <N>] [-t --tail] [NAME]...`](/cli/logs.md)
+- [`pitchfork run [-f --force] <NAME> [CMD]...`](/cli/run.md)
+- [`pitchfork start [NAME]...`](/cli/start.md)
+- [`pitchfork usage`](/cli/usage.md)
diff --git a/docs/cli/run.md b/docs/cli/run.md
@@ -12,6 +12,10 @@ Name of the daemon to run
 
 ### `[CMD]...`
 
+Runs a one-off daemon
+
 ## Flags
 
 ### `-f --force`
+
+Runs a one-off daemon
diff --git a/mise.toml b/mise.toml
@@ -24,7 +24,8 @@ run = "cargo build"
 depends = ["build"]
 run = [
   "pitchfork usage > pitchfork.usage.kdl",
-  "usage g markdown -mf pitchfork.usage.kdl --out-dir docs/cli",
+  "usage g markdown -mf pitchfork.usage.kdl --out-dir docs/cli --url-prefix /cli",
+  "usage g json -f pitchfork.usage.kdl > docs/cli/commands.json",
   "git add pitchfork.usage.kdl docs",
 ]