Generate mdx for cli actions (#4499)

Duplicate existing reference docs generation to cover cli actions. Docs
update pass to make the structure consistent.

See https://github.com/ghostty-org/website/pull/253 for website changes.

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,

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 };
 }
 

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");
+        }
+    }
+}

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`.

src/cli/action.zig

@@ -45,12 +45,12 @@ pub const Action = enum {
     // Validate passed config file
     @"validate-config",
 
-    // List, (eventually) view, and (eventually) send crash reports.
-    @"crash-report",
-
     // Show which font face Ghostty loads a codepoint from.
     @"show-face",
 
+    // List, (eventually) view, and (eventually) send crash reports.
+    @"crash-report",
+
     pub const Error = error{
         /// Multiple actions were detected. You can specify at most one
         /// action on the CLI otherwise the behavior desired is ambiguous.

src/cli/help.zig

@@ -15,9 +15,11 @@ pub const Options = struct {
     }
 };
 
-/// The `help` command shows general help about Ghostty. You can also specify
-/// `--help` or `-h` along with any action such as `+list-themes` to see help
-/// for a specific action.
+/// The `help` command shows general help about Ghostty. Recognized as either
+/// `-h, `--help`, or like other actions `+help`.
+///
+/// You can also specify `--help` or `-h` along with any action such as
+/// `+list-themes` to see help for a specific action.
 pub fn run(alloc: Allocator) !u8 {
     var opts: Options = .{};
     defer opts.deinit();

src/cli/list_actions.zig

@@ -24,7 +24,9 @@ pub const Options = struct {
 /// actions for Ghostty. These are distinct from the CLI Actions which can
 /// be listed via `+help`
 ///
-/// The `--docs` argument will print out the documentation for each action.
+/// Flags:
+///
+///   * `--docs`: will print out the documentation for each action.
 pub fn run(alloc: Allocator) !u8 {
     var opts: Options = .{};
     defer opts.deinit();

src/cli/list_fonts.zig

@@ -44,14 +44,21 @@ pub const Options = struct {
 /// the sorting will be disabled and the results instead will be shown in the
 /// same priority order Ghostty would use to pick a font.
 ///
-/// The `--family` argument can be used to filter results to a specific family.
-/// The family handling is identical to the `font-family` set of Ghostty
-/// configuration values, so this can be used to debug why your desired font may
-/// not be loading.
+/// Flags:
 ///
-/// The `--bold` and `--italic` arguments can be used to filter results to
-/// specific styles. It is not guaranteed that only those styles are returned,
-/// it will just prioritize fonts that match those styles.
+///   * `--bold`: Filter results to specific bold styles. It is not guaranteed
+///     that only those styles are returned. They are only prioritized.
+///
+///   * `--italic`: Filter results to specific italic styles. It is not guaranteed
+///     that only those styles are returned. They are only prioritized.
+///
+///   * `--style`: Filter results based on the style string advertised by a font.
+///     It is not guaranteed that only those styles are returned. They are only
+///     prioritized.
+///
+///   * `--family`: Filter results to a specific font family. The family handling
+///     is identical to the `font-family` set of Ghostty configuration values, so
+///     this can be used to debug why your desired font may not be loading.
 pub fn run(alloc: Allocator) !u8 {
     var iter = try args.argsIterator(alloc);
     defer iter.deinit();

src/cli/list_keybinds.zig

@@ -42,10 +42,14 @@ pub const Options = struct {
 /// changes to the keybinds it will print out the default ones configured for
 /// Ghostty
 ///
-/// The `--default` argument will print out all the default keybinds configured
-/// for Ghostty
+/// Flags:
 ///
-/// The `--plain` flag will disable formatting and make the output more
+///   * `--default`: will print out all the default keybinds
+///
+///   * `--docs`: currently does nothing, intended to print out documentation
+///     about the action associated with the keybinds
+///
+///   * `--plain`: will disable formatting and make the output more
 ///     friendly for Unix tooling. This is default when not printing to a tty.
 pub fn run(alloc: Allocator) !u8 {
     var opts: Options = .{};

src/cli/list_themes.zig

@@ -91,6 +91,7 @@ const ThemeListElement = struct {
 /// Flags:
 ///
 ///   * `--path`: Show the full path to the theme.
+///
 ///   * `--plain`: Force a plain listing of themes.
 pub fn run(gpa_alloc: std.mem.Allocator) !u8 {
     var opts: Options = .{};

src/cli/validate_config.zig

@@ -23,10 +23,13 @@ pub const Options = struct {
 
 /// The `validate-config` command is used to validate a Ghostty config file.
 ///
-/// When executed without any arguments, this will load the config from the default location.
+/// When executed without any arguments, this will load the config from the default
+/// location.
 ///
-/// The `--config-file` argument can be passed to validate a specific target config
-/// file in a non-default location.
+/// Flags:
+///
+///   * `--config-file`: can be passed to validate a specific target config file in
+///     a non-default location
 pub fn run(alloc: std.mem.Allocator) !u8 {
     var opts: Options = .{};
     defer opts.deinit();

src/cli/version.zig

@@ -10,7 +10,8 @@ const gtk = if (build_config.app_runtime == .gtk) @import("../apprt/gtk/c.zig").
 
 pub const Options = struct {};
 
-/// The `version` command is used to display information about Ghostty.
+/// The `version` command is used to display information about Ghostty. Recognized as
+/// either `+version` or `--version`.
 pub fn run(alloc: Allocator) !u8 {
     _ = alloc;
 

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"),

src/shell-integration/README.md

@@ -6,7 +6,7 @@ supports.
 
 This README is meant as developer documentation and not as
 user documentation. For user documentation, see the main
-README.
+README or [ghostty.org](https://ghostty.org/docs)
 
 ## Implementation Details