From 098a46f0773c544b07e8d812247719893f1b6b6d Mon Sep 17 00:00:00 2001
From: Anund <anundm@gmail.com>
Date: Wed, 8 Jan 2025 17:32:11 +1100
Subject: [PATCH] docs: generate mdx file for cli actions

---
 src/build/Config.zig               |  1 +
 src/build/GhosttyWebdata.zig       | 29 +++++++++++++++++
 src/build/webgen/main_commands.zig | 51 ++++++++++++++++++++++++++++++
 src/cli/README.md                  | 13 ++++++++
 src/main.zig                       |  1 +
 5 files changed, 95 insertions(+)
 create mode 100644 src/build/webgen/main_commands.zig
 create mode 100644 src/cli/README.md

diff --git a/src/build/Config.zig b/src/build/Config.zig
index 71dffce4a..b65a8d566 100644
--- a/src/build/Config.zig
+++ b/src/build/Config.zig
@@ -486,6 +486,7 @@ pub const ExeEntrypoint = enum {
     mdgen_ghostty_5,
     webgen_config,
     webgen_actions,
+    webgen_commands,
     bench_parser,
     bench_stream,
     bench_codepoint_width,
diff --git a/src/build/GhosttyWebdata.zig b/src/build/GhosttyWebdata.zig
index 6e0acaf17..860feb705 100644
--- a/src/build/GhosttyWebdata.zig
+++ b/src/build/GhosttyWebdata.zig
@@ -73,6 +73,35 @@ pub fn init(
         ).step);
     }
 
+    {
+        const webgen_commands = b.addExecutable(.{
+            .name = "webgen_commands",
+            .root_source_file = b.path("src/main.zig"),
+            .target = b.host,
+        });
+        deps.help_strings.addImport(webgen_commands);
+
+        {
+            const buildconfig = config: {
+                var copy = deps.config.*;
+                copy.exe_entrypoint = .webgen_commands;
+                break :config copy;
+            };
+
+            const options = b.addOptions();
+            try buildconfig.addOptions(options);
+            webgen_commands.root_module.addOptions("build_options", options);
+        }
+
+        const webgen_commands_step = b.addRunArtifact(webgen_commands);
+        const webgen_commands_out = webgen_commands_step.captureStdOut();
+
+        try steps.append(&b.addInstallFile(
+            webgen_commands_out,
+            "share/ghostty/webdata/commands.mdx",
+        ).step);
+    }
+
     return .{ .steps = steps.items };
 }
 
diff --git a/src/build/webgen/main_commands.zig b/src/build/webgen/main_commands.zig
new file mode 100644
index 000000000..6e6b00c5e
--- /dev/null
+++ b/src/build/webgen/main_commands.zig
@@ -0,0 +1,51 @@
+const std = @import("std");
+const Action = @import("../../cli/action.zig").Action;
+const help_strings = @import("help_strings");
+
+pub fn main() !void {
+    const output = std.io.getStdOut().writer();
+    try genActions(output);
+}
+
+// Note: as a shortcut for defining inline editOnGithubLinks per cli action the user
+// is directed to the folder view on Github. This includes a README pointing them to 
+// the files to edit.
+pub fn genActions(writer: anytype) !void {
+    // Write the header
+    try writer.writeAll(
+        \\---
+        \\title: Reference
+        \\description: Reference of all Ghostty action subcommands.
+        \\editOnGithubLink: https://github.com/ghostty-org/ghostty/tree/main/src/cli
+        \\---
+        \\Ghostty includes a number of utility actions that can be accessed as subcommands.
+        \\Actions provide utilities to work with config, list keybinds, list fonts, demo themes,
+        \\and debug.
+        \\
+    );
+
+    inline for (@typeInfo(Action).Enum.fields) |field| {
+        const action = std.meta.stringToEnum(Action, field.name).?;
+
+        switch (action) {
+            .help, .version => try writer.writeAll("## " ++ field.name ++ "\n"),
+            else => try writer.writeAll("## " ++ field.name ++ "\n"),
+        }
+
+        if (@hasDecl(help_strings.Action, field.name)) {
+            var iter = std.mem.splitScalar(u8, @field(help_strings.Action, field.name), '\n');
+            var first = true;
+            while (iter.next()) |s| {
+                try writer.writeAll(s);
+                try writer.writeAll("\n");
+                first = false;
+            }
+            try writer.writeAll("\n```\n");
+            switch (action) {
+                .help, .version => try writer.writeAll("ghostty --" ++ field.name ++ "\n"),
+                else => try writer.writeAll("ghostty +" ++ field.name ++ "\n"),
+            }
+            try writer.writeAll("```\n\n");
+        }
+    }
+}
diff --git a/src/cli/README.md b/src/cli/README.md
new file mode 100644
index 000000000..7a1d99409
--- /dev/null
+++ b/src/cli/README.md
@@ -0,0 +1,13 @@
+# Subcommand Actions
+
+This is the cli specific code. It contains cli actions and tui definitions and
+argument parsing.
+
+This README is meant as developer documentation and not as user documentation.
+For user documentation, see the main README or [ghostty.org](https://ghostty.org/docs).
+
+## Updating documentation
+
+Each cli action is defined in it's own file. Documentation for each action is defined
+in the doc comment associated with the `run` function. For example the `run` function
+in `list_keybinds.zig` contains the help text for `ghostty +list-keybinds`.
diff --git a/src/main.zig b/src/main.zig
index ecf38fbb3..121a3b7d2 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -9,6 +9,7 @@ const entrypoint = switch (build_config.exe_entrypoint) {
     .mdgen_ghostty_5 => @import("build/mdgen/main_ghostty_5.zig"),
     .webgen_config => @import("build/webgen/main_config.zig"),
     .webgen_actions => @import("build/webgen/main_actions.zig"),
+    .webgen_commands => @import("build/webgen/main_commands.zig"),
     .bench_parser => @import("bench/parser.zig"),
     .bench_stream => @import("bench/stream.zig"),
     .bench_codepoint_width => @import("bench/codepoint-width.zig"),