chore: doc search

jdx · Feb 16, 2025 · d0152e7 · d0152e7
1 parent 241e294
commit d0152e7
Show file tree

Hide file tree

Showing 8 changed files with 430 additions and 249 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -20,7 +20,7 @@ path = "src/main.rs"
 [dependencies]
 chrono = "0.4"
 clap = { version = "4", features = ["derive"] }
-clap_usage = "1"
+clap_usage = "2"
 comfy-table = "7.1.3"
 console = "0.15"
 dirs = "5"

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -44,4 +44,7 @@ export default defineConfig({
     logo: "/logo.png",
   },
   head: [["link", { rel: "icon", href: "/img/favicon.ico" }]],
+  search: {
+    provider: "local",
+  }
 });
diff --git a/docs/cli/commands.json b/docs/cli/commands.json
@@ -18,6 +18,7 @@
             "help": "The shell to generate source for",
             "help_first_line": "The shell to generate source for",
             "required": true,
+            "double_dash": "Optional",
             "hide": false
           }
         ],
@@ -53,6 +54,7 @@
               "name": "SHELL_PID",
               "usage": "<SHELL_PID>",
               "required": true,
+              "double_dash": "Optional",
               "hide": false
             }
           }
@@ -102,6 +104,7 @@
                 "help": "ID of the daemon to add",
                 "help_first_line": "ID of the daemon to add",
                 "required": true,
+                "double_dash": "Optional",
                 "hide": false
               },
               {
@@ -110,6 +113,7 @@
                 "help": "Arguments to pass to the daemon",
                 "help_first_line": "Arguments to pass to the daemon",
                 "required": false,
+                "double_dash": "Automatic",
                 "var": true,
                 "hide": false
               }
@@ -164,6 +168,7 @@
                 "help": "The ID of the daemon to remove",
                 "help_first_line": "The ID of the daemon to remove",
                 "required": true,
+                "double_dash": "Optional",
                 "hide": false
               }
             ],
@@ -205,6 +210,7 @@
             "help": "The shell to generate completion for",
             "help_first_line": "The shell to generate completion for",
             "required": true,
+            "double_dash": "Optional",
             "hide": false
           }
         ],
@@ -230,6 +236,7 @@
             "help": "Name of the daemon to disable",
             "help_first_line": "Name of the daemon to disable",
             "required": true,
+            "double_dash": "Optional",
             "hide": false
           }
         ],
@@ -257,6 +264,7 @@
             "help": "Name of the daemon to enable",
             "help_first_line": "Name of the daemon to enable",
             "required": true,
+            "double_dash": "Optional",
             "hide": false
           }
         ],
@@ -315,6 +323,7 @@
             "help": "Show only logs for the specified daemon(s)",
             "help_first_line": "Show only logs for the specified daemon(s)",
             "required": false,
+            "double_dash": "Optional",
             "var": true,
             "hide": false
           }
@@ -350,6 +359,7 @@
               "name": "N",
               "usage": "<N>",
               "required": true,
+              "double_dash": "Optional",
               "hide": false
             }
           },
@@ -382,7 +392,7 @@
         "full_cmd": [
           "run"
         ],
-        "usage": "run [-f --force] <ID> [RUN]...",
+        "usage": "run [-f --force] <ID> [-- RUN]...",
         "subcommands": {},
         "args": [
           {
@@ -391,12 +401,14 @@
             "help": "Name of the daemon to run",
             "help_first_line": "Name of the daemon to run",
             "required": true,
+            "double_dash": "Optional",
             "hide": false
           },
           {
             "name": "RUN",
-            "usage": "[RUN]...",
+            "usage": "[-- RUN]...",
             "required": false,
+            "double_dash": "Required",
             "var": true,
             "hide": false
           }
@@ -438,6 +450,7 @@
             "help": "ID of the daemon(s) in pitchfork.toml to start",
             "help_first_line": "ID of the daemon(s) in pitchfork.toml to start",
             "required": false,
+            "double_dash": "Optional",
             "var": true,
             "hide": false
           }
@@ -470,6 +483,7 @@
               "name": "SHELL_PID",
               "usage": "<SHELL_PID>",
               "required": true,
+              "double_dash": "Optional",
               "hide": false
             }
           },
@@ -509,6 +523,7 @@
             "name": "ID",
             "usage": "<ID>",
             "required": true,
+            "double_dash": "Optional",
             "hide": false
           }
         ],
@@ -536,6 +551,7 @@
             "help": "The name of the daemon to stop",
             "help_first_line": "The name of the daemon to stop",
             "required": false,
+            "double_dash": "Optional",
             "var": true,
             "hide": false
           }
@@ -699,6 +715,7 @@
             "help": "The name of the daemon to wait for",
             "help_first_line": "The name of the daemon to wait for",
             "required": true,
+            "double_dash": "Optional",
             "hide": false
           }
         ],

diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -18,7 +18,7 @@
 - [`pitchfork enable <ID>`](/cli/enable.md)
 - [`pitchfork list [--hide-header]`](/cli/list.md)
 - [`pitchfork logs [FLAGS] [ID]...`](/cli/logs.md)
-- [`pitchfork run [-f --force] <ID> [RUN]...`](/cli/run.md)
+- [`pitchfork run [-f --force] <ID> [-- RUN]...`](/cli/run.md)
 - [`pitchfork start [-a --all] [-f --force] [ID]...`](/cli/start.md)
 - [`pitchfork status <ID>`](/cli/status.md)
 - [`pitchfork stop [ID]...`](/cli/stop.md)

diff --git a/docs/cli/run.md b/docs/cli/run.md
@@ -1,6 +1,6 @@
 # `pitchfork run`
 
-- **Usage**: `pitchfork run [-f --force] <ID> [RUN]...`
+- **Usage**: `pitchfork run [-f --force] <ID> [-- RUN]...`
 - **Aliases**: `r`
 
 Runs a one-off daemon
@@ -11,12 +11,8 @@ Runs a one-off daemon
 
 Name of the daemon to run
 
-### `[RUN]...`
-
-Runs a one-off daemon
+### `[-- RUN]...`
 
 ## Flags
 
 ### `-f --force`
-
-Runs a one-off daemon
diff --git a/docs/cli/status.md b/docs/cli/status.md
@@ -8,5 +8,3 @@ Display the status of a daemon
 ## Arguments
 
 ### `<ID>`
-
-Display the status of a daemon
diff --git a/pitchfork.usage.kdl b/pitchfork.usage.kdl
@@ -1,109 +1,101 @@
-name "pitchfork"
-bin "pitchfork"
+name pitchfork
+bin pitchfork
 version "0.1.5"
 about "Daemons with DX"
 usage "Usage: pitchfork <COMMAND>"
-cmd "activate" help="Activate pitchfork in your shell session" {
-    long_help r"Activate pitchfork in your shell session
-
-Necessary for autostart/stop when entering/exiting projects with pitchfork.toml files"
-    arg "<SHELL>" help="The shell to generate source for"
+cmd activate help="Activate pitchfork in your shell session" {
+    long_help "Activate pitchfork in your shell session\n\nNecessary for autostart/stop when entering/exiting projects with pitchfork.toml files"
+    arg <SHELL> help="The shell to generate source for"
 }
-cmd "cd" hide=true {
-    flag "--shell-pid" required=true {
-        arg "<SHELL_PID>"
+cmd cd hide=#true {
+    flag --shell-pid required=#true {
+        arg <SHELL_PID>
     }
 }
-cmd "clean" help="Removes stopped/failed daemons from `pitchfork list`" {
-    alias "c"
-}
-cmd "config" help="manage/edit pitchfork.toml files" {
-    alias "cfg"
-    long_help r"manage/edit pitchfork.toml files
-
-without a subcommand, lists all pitchfork.toml files from the current directory"
-    cmd "add" help="Add a new daemon to ./pitchfork.toml" {
-        alias "a"
-        flag "--autostart" help="Autostart the daemon when entering the directory"
-        flag "--autostop" help="Autostop the daemon when leaving the directory"
-        arg "<ID>" help="ID of the daemon to add"
-        arg "[ARGS]..." help="Arguments to pass to the daemon" var=true
+cmd clean help="Removes stopped/failed daemons from `pitchfork list`" {
+    alias c
+}
+cmd config help="manage/edit pitchfork.toml files" {
+    alias cfg
+    long_help "manage/edit pitchfork.toml files\n\nwithout a subcommand, lists all pitchfork.toml files from the current directory"
+    cmd add help="Add a new daemon to ./pitchfork.toml" {
+        alias a
+        flag --autostart help="Autostart the daemon when entering the directory"
+        flag --autostop help="Autostop the daemon when leaving the directory"
+        arg <ID> help="ID of the daemon to add"
+        arg "[ARGS]..." help="Arguments to pass to the daemon" required=#false double_dash=automatic var=#true
     }
-    cmd "remove" help="Remove a daemon from pitchfork.toml" {
-        alias "rm"
-        arg "<ID>" help="The ID of the daemon to remove"
+    cmd remove help="Remove a daemon from pitchfork.toml" {
+        alias rm
+        arg <ID> help="The ID of the daemon to remove"
     }
 }
-cmd "completion" help="Generates shell completion scripts" {
-    arg "<SHELL>" help="The shell to generate completion for"
+cmd completion help="Generates shell completion scripts" {
+    arg <SHELL> help="The shell to generate completion for"
 }
-cmd "disable" help="Prevent a daemon from restarting" {
-    alias "d"
-    arg "<ID>" help="Name of the daemon to disable"
+cmd disable help="Prevent a daemon from restarting" {
+    alias d
+    arg <ID> help="Name of the daemon to disable"
 }
-cmd "enable" help="Allow a daemon to start" {
-    alias "e"
-    arg "<ID>" help="Name of the daemon to enable"
+cmd enable help="Allow a daemon to start" {
+    alias e
+    arg <ID> help="Name of the daemon to enable"
 }
-cmd "list" help="List all daemons" {
-    alias "ls"
-    flag "--hide-header" help="Show header"
+cmd list help="List all daemons" {
+    alias ls
+    flag --hide-header help="Show header"
 }
-cmd "logs" help="Displays logs for daemon(s)" {
-    alias "l"
+cmd logs help="Displays logs for daemon(s)" {
+    alias l
     flag "-c --clear" help="Delete logs"
-    flag "-n" help="Show N lines of logs" {
+    flag -n help="Show N lines of logs" {
         long_help "Show N lines of logs\n\nSet to 0 to show all logs"
-        arg "<N>"
+        arg <N>
     }
     flag "-t --tail" help="Show logs in real-time"
-    arg "[ID]..." help="Show only logs for the specified daemon(s)" var=true
+    arg "[ID]..." help="Show only logs for the specified daemon(s)" required=#false var=#true
 }
-cmd "run" help="Runs a one-off daemon" {
-    alias "r"
+cmd run help="Runs a one-off daemon" {
+    alias r
     flag "-f --force"
-    arg "<ID>" help="Name of the daemon to run"
-    arg "[RUN]..." var=true
+    arg <ID> help="Name of the daemon to run"
+    arg "[-- RUN]..." required=#false var=#true
 }
-cmd "start" help="Starts a daemon from a pitchfork.toml file" {
-    alias "s"
+cmd start help="Starts a daemon from a pitchfork.toml file" {
+    alias s
     flag "-a --all" help="Start all daemons in all pitchfork.tomls"
-    flag "--shell-pid" hide=true {
-        arg "<SHELL_PID>"
+    flag --shell-pid hide=#true {
+        arg <SHELL_PID>
     }
     flag "-f --force" help="Stop the daemon if it is already running"
-    arg "[ID]..." help="ID of the daemon(s) in pitchfork.toml to start" var=true
+    arg "[ID]..." help="ID of the daemon(s) in pitchfork.toml to start" required=#false var=#true
 }
-cmd "status" help="Display the status of a daemon" {
-    alias "stat"
-    arg "<ID>"
+cmd status help="Display the status of a daemon" {
+    alias stat
+    arg <ID>
 }
-cmd "stop" help="Sends a stop signal to a daemon" {
-    alias "kill"
-    arg "[ID]..." help="The name of the daemon to stop" var=true
+cmd stop help="Sends a stop signal to a daemon" {
+    alias kill
+    arg "[ID]..." help="The name of the daemon to stop" required=#false var=#true
 }
-cmd "supervisor" subcommand_required=true help="Start, stop, and check the status of the pitchfork supervisor daemon" {
-    alias "sup"
-    cmd "run" help="Runs the internal pitchfork daemon in the foreground" {
+cmd supervisor subcommand_required=#true help="Start, stop, and check the status of the pitchfork supervisor daemon" {
+    alias sup
+    cmd run help="Runs the internal pitchfork daemon in the foreground" {
         flag "-f --force" help="kill existing daemon"
     }
-    cmd "start" help="Starts the internal pitchfork daemon in the background" {
+    cmd start help="Starts the internal pitchfork daemon in the background" {
         flag "-f --force" help="kill existing daemon"
     }
-    cmd "status" help="Gets the status of the pitchfork daemon"
-    cmd "stop" help="Stops the internal pitchfork daemon running in the background"
+    cmd status help="Gets the status of the pitchfork daemon"
+    cmd stop help="Stops the internal pitchfork daemon running in the background"
 }
-cmd "usage" hide=true help="Generates a usage spec for the CLI" {
-    long_help r"Generates a usage spec for the CLI
-
-https://usage.jdx.dev"
+cmd usage hide=#true help="Generates a usage spec for the CLI" {
+    long_help "Generates a usage spec for the CLI\n\nhttps://usage.jdx.dev"
 }
-cmd "wait" help="Wait for a daemon to stop, tailing the logs along the way" {
-    alias "w"
-    long_help r"Wait for a daemon to stop, tailing the logs along the way
-
-Exits with the same status code as the daemon"
-    arg "<ID>" help="The name of the daemon to wait for"
+cmd wait help="Wait for a daemon to stop, tailing the logs along the way" {
+    alias w
+    long_help "Wait for a daemon to stop, tailing the logs along the way\n\nExits with the same status code as the daemon"
+    arg <ID> help="The name of the daemon to wait for"
 }
 
 complete "id" run="pitchfork ls | awk '{print $1}'"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,5 +8,3 @@ Display the status of a daemon
		## Arguments

		### `<ID>`

		Display the status of a daemon