Applied-Software/ghostty
5
0
Fork 0
mirror of https://github.com/ghostty-org/ghostty.git synced 2025-07-16 08:46:08 +03:00
Code Issues Packages Projects Releases Wiki Activity

Fixed documentation generation in list-actions --docs command (#4974)

Browse Source 
Fixes https://github.com/ghostty-org/ghostty/issues/4958

## Changes

1. Fixed documentation generation in `actions.mdx`:

- Fixed an issue where the last action's documentation was [not properly
generated](fe6c69263c/docs/config/keybind/reference.mdx (crash))
   
- Ensured all actions' documentation is correctly included in the output

2. Improved `ghostty +list-actions --docs` command output formatting:

   - Grouped related actions together with shared documentation
   
   - Added proper spacing between action groups
  
<details> 
    <summary>ghostty-dev +list-actions --docs</summary>

```
ignore:
  Ignore this key combination, don't send it to the child process, just
  black hole it.

unbind:
  This action is used to flag that the binding should be removed from
  the set. This should never exist in an active set and `set.put` has an
  assertion to verify this.

csi:
  Send a CSI sequence. The value should be the CSI sequence without the
  CSI header (`ESC [` or `\x1b[`).

esc:
  Send an `ESC` sequence.

text:
  Send the given text. Uses Zig string literal syntax. This is currently
  not validated. If the text is invalid (i.e. contains an invalid escape
  sequence), the error will currently only show up in logs.

cursor_key:
  Send data to the pty depending on whether cursor key mode is enabled
  (`application`) or disabled (`normal`).

reset:
  Reset the terminal. This can fix a lot of issues when a running
  program puts the terminal into a broken state. This is equivalent to
  when you type "reset" and press enter.

  If you do this while in a TUI program such as vim, this may break
  the program. If you do this while in a shell, you may have to press
  enter after to get a new prompt.

copy_to_clipboard:
paste_from_clipboard:
paste_from_selection:
  Copy and paste.

copy_url_to_clipboard:
  Copy the URL under the cursor to the clipboard. If there is no
  URL under the cursor, this does nothing.

increase_font_size:
decrease_font_size:
  Increase/decrease the font size by a certain amount.

reset_font_size:
  Reset the font size to the original configured size.

clear_screen:
  Clear the screen. This also clears all scrollback.

select_all:
  Select all text on the screen.

scroll_to_top:
scroll_to_bottom:
scroll_page_up:
scroll_page_down:
scroll_page_fractional:
scroll_page_lines:
  Scroll the screen varying amounts.

adjust_selection:
  Adjust an existing selection in a given direction. This action
  does nothing if there is no active selection.

jump_to_prompt:
  Jump the viewport forward or back by prompt. Positive number is the
  number of prompts to jump forward, negative is backwards.

write_scrollback_file:
  Write the entire scrollback into a temporary file. The action
  determines what to do with the filepath. Valid values are:

    - "paste": Paste the file path into the terminal.
    - "open": Open the file in the default OS editor for text files.
      The default OS editor is determined by using `open` on macOS
      and `xdg-open` on Linux.

write_screen_file:
  Same as write_scrollback_file but writes the full screen contents.
  See write_scrollback_file for available values.

write_selection_file:
  Same as write_scrollback_file but writes the selected text.
  If there is no selected text this does nothing (it doesn't
  even create an empty file). See write_scrollback_file for
  available values.

new_window:
  Open a new window. If the application isn't currently focused,
  this will bring it to the front.

new_tab:
  Open a new tab.

previous_tab:
  Go to the previous tab.

next_tab:
  Go to the next tab.

last_tab:
  Go to the last tab (the one with the highest index)

goto_tab:
  Go to the tab with the specific number, 1-indexed. If the tab number
  is higher than the number of tabs, this will go to the last tab.

move_tab:
  Moves a tab by a relative offset.
  Adjusts the tab position based on `offset`. For example `move_tab:-1` for left, `move_tab:1` for right.
  If the new position is out of bounds, it wraps around cyclically within the tab range.

toggle_tab_overview:
  Toggle the tab overview.
  This only works with libadwaita enabled currently.

new_split:
  Create a new split in the given direction. The new split will appear in
  the direction given. For example `new_split:up`. Valid values are left, right, up, down and auto.

goto_split:
  Focus on a split in a given direction. For example `goto_split:up`.
  Valid values are left, right, up, down, previous and next.

toggle_split_zoom:
  zoom/unzoom the current split.

resize_split:
  Resize the current split by moving the split divider in the given
  direction. For example `resize_split:left,10`. The valid directions are up, down, left and right.

equalize_splits:
  Equalize all splits in the current window

inspector:
  Show, hide, or toggle the terminal inspector for the currently focused
  terminal.

open_config:
  Open the configuration file in the default OS editor. If your default OS
  editor isn't configured then this will fail. Currently, any failures to
  open the configuration will show up only in the logs.

reload_config:
  Reload the configuration. The exact meaning depends on the app runtime
  in use but this usually involves re-reading the configuration file
  and applying any changes. Note that not all changes can be applied at
  runtime.

close_surface:
  Close the current "surface", whether that is a window, tab, split, etc.
  This only closes ONE surface. This will trigger close confirmation as
  configured.

close_tab:
  Close the current tab, regardless of how many splits there may be.
  This will trigger close confirmation as configured.

close_window:
  Close the window, regardless of how many tabs or splits there may be.
  This will trigger close confirmation as configured.

close_all_windows:
  Close all windows. This will trigger close confirmation as configured.
  This only works for macOS currently.

toggle_fullscreen:
  Toggle fullscreen mode of window.

toggle_window_decorations:
  Toggle window decorations on and off. This only works on Linux.

toggle_secure_input:
  Toggle secure input mode on or off. This is used to prevent apps
  that monitor input from seeing what you type. This is useful for
  entering passwords or other sensitive information.

  This applies to the entire application, not just the focused
  terminal. You must toggle it off to disable it, or quit Ghostty.

  This only works on macOS, since this is a system API on macOS.

toggle_quick_terminal:
  Toggle the "quick" terminal. The quick terminal is a terminal that
  appears on demand from a keybinding, often sliding in from a screen
  edge such as the top. This is useful for quick access to a terminal
  without having to open a new window or tab.

  When the quick terminal loses focus, it disappears. The terminal state
  is preserved between appearances, so you can always press the keybinding
  to bring it back up.

  To enable the quick terminally globally so that Ghostty doesn't
  have to be focused, prefix your keybind with `global`. Example:

  \```ini
  keybind = global:cmd+grave_accent=toggle_quick_terminal
  \```

  The quick terminal has some limitations:

    - It is a singleton; only one instance can exist at a time.
    - It does not support tabs, but it does support splits.
    - It will not be restored when the application is restarted
      (for systems that support window restoration).
    - It supports fullscreen, but fullscreen will always be a non-native
      fullscreen (macos-non-native-fullscreen = true). This only applies
      to the quick terminal window. This is a requirement due to how
      the quick terminal is rendered.

  See the various configurations for the quick terminal in the
  configuration file to customize its behavior.

  This currently only works on macOS.

toggle_visibility:
  Show/hide all windows. If all windows become shown, we also ensure
  Ghostty becomes focused. When hiding all windows, focus is yielded
  to the next application as determined by the OS.

  This currently only works on macOS.

quit:
  Quit ghostty.

crash:
  Crash ghostty in the desired thread for the focused surface.

  WARNING: This is a hard crash (panic) and data can be lost.

  The purpose of this action is to test crash handling. For some
  users, it may be useful to test crash reporting functionality in
  order to determine if it all works as expected.

  The value determines the crash location:

    - "main" - crash on the main (GUI) thread.
    - "io" - crash on the IO thread for the focused surface.
    - "render" - crash on the render thread for the focused surface.

```
</details>

## Testing

- Run `ghostty-dev +list-actions --docs` to verify the new output format

- Check generated _zig-out/share/ghostty/webdata/actions.mdx_ to ensure
all actions are properly documented
This commit is contained in:
Mitchell Hashimoto
2025-02-11 12:47:47 -08:00
committed by GitHub
parent 4b77a1c71e 0016199ec3
commit f3d0c7c2ad
4 changed files with 114 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
src/build/webgen/main_actions.zig
View File

@ -1,58 +1,8 @@
const std = @import("std"); const std = @import("std");
const help_strings = @import("help_strings"); const help_strings = @import("help_strings");
const KeybindAction = @import("../../input/Binding.zig").Action; const helpgen_actions = @import("../../helpgen_actions.zig");
pub fn main() !void { pub fn main() !void {
const output = std.io.getStdOut().writer(); const output = std.io.getStdOut().writer();
try genKeybindActions(output); try helpgen_actions.generate(output, .markdown, std.heap.page_allocator);
}
pub fn genKeybindActions(writer: anytype) !void {
// Write the header
try writer.writeAll(
\\---
\\title: Keybinding Action Reference
\\description: Reference of all Ghostty keybinding actions.
\\editOnGithubLink: https://github.com/ghostty-org/ghostty/edit/main/src/input/Binding.zig
\\---
\\
\\This is a reference of all Ghostty keybinding actions.
\\
\\
);
@setEvalBranchQuota(5_000);
var buffer = std.ArrayList(u8).init(std.heap.page_allocator);
defer buffer.deinit();
const fields = @typeInfo(KeybindAction).Union.fields;
inline for (fields) |field| {
if (field.name[0] == '_') continue;
// Write previously stored doc comment below all related actions
if (@hasDecl(help_strings.KeybindAction, field.name)) {
try writer.writeAll(buffer.items);
try writer.writeAll("\n");
buffer.clearRetainingCapacity();
}
// Write the field name.
try writer.writeAll("## `");
try writer.writeAll(field.name);
try writer.writeAll("`\n");
if (@hasDecl(help_strings.KeybindAction, field.name)) {
var iter = std.mem.splitScalar(
u8,
@field(help_strings.KeybindAction, field.name),
'\n',
);
while (iter.next()) |s| {
try buffer.appendSlice(s);
try buffer.appendSlice("\n");
}
}
}
} }

16
src/cli/list_actions.zig
View File

@ -2,7 +2,7 @@ const std = @import("std");
const args = @import("args.zig"); const args = @import("args.zig");
const Action = @import("action.zig").Action; const Action = @import("action.zig").Action;
const Allocator = std.mem.Allocator; const Allocator = std.mem.Allocator;
const help_strings = @import("help_strings"); const helpgen_actions = @import("../helpgen_actions.zig");
pub const Options = struct { pub const Options = struct {
/// If `true`, print out documentation about the action associated with the /// If `true`, print out documentation about the action associated with the
@ -38,19 +38,7 @@ pub fn run(alloc: Allocator) !u8 {
} }
const stdout = std.io.getStdOut().writer(); const stdout = std.io.getStdOut().writer();
const info = @typeInfo(help_strings.KeybindAction); try helpgen_actions.generate(stdout, .plaintext, std.heap.page_allocator);
inline for (info.Struct.decls) |field| {
try stdout.print("{s}", .{field.name});
if (opts.docs) {
try stdout.print(":\n", .{});
var iter = std.mem.splitScalar(u8, std.mem.trimRight(u8, @field(help_strings.KeybindAction, field.name), &std.ascii.whitespace), '\n');
while (iter.next()) |line| {
try stdout.print(" {s}\n", .{line});
}
} else {
try stdout.print("\n", .{});
}
}
return 0; return 0;
} }

6
src/input/Binding.zig
View File

@ -236,9 +236,9 @@ pub const Action = union(enum) {
/// Send an `ESC` sequence. /// Send an `ESC` sequence.
esc: []const u8, esc: []const u8,
// Send the given text. Uses Zig string literal syntax. This is currently /// Send the given text. Uses Zig string literal syntax. This is currently
// not validated. If the text is invalid (i.e. contains an invalid escape /// not validated. If the text is invalid (i.e. contains an invalid escape
// sequence), the error will currently only show up in logs. /// sequence), the error will currently only show up in logs.
text: []const u8, text: []const u8,
/// Send data to the pty depending on whether cursor key mode is enabled /// Send data to the pty depending on whether cursor key mode is enabled

107
src/input/helpgen_actions.zig Normal file
View File

@ -0,0 +1,107 @@
//! This module is a help generator for keybind actions documentation.
//! It can generate documentation in different formats (plaintext for CLI,
//! markdown for website) while maintaining consistent content.
const std = @import("std");
const KeybindAction = @import("Binding.zig").Action;
const help_strings = @import("help_strings");
/// Format options for generating keybind actions documentation
pub const Format = enum {
/// Plain text output with indentation
plaintext,
/// Markdown formatted output
markdown,
fn formatFieldName(self: Format, writer: anytype, field_name: []const u8) !void {
switch (self) {
.plaintext => {
try writer.writeAll(field_name);
try writer.writeAll(":\n");
},
.markdown => {
try writer.writeAll("## `");
try writer.writeAll(field_name);
try writer.writeAll("`\n");
},
}
}
fn formatDocLine(self: Format, writer: anytype, line: []const u8) !void {
switch (self) {
.plaintext => {
try writer.appendSlice(" ");
try writer.appendSlice(line);
try writer.appendSlice("\n");
},
.markdown => {
try writer.appendSlice(line);
try writer.appendSlice("\n");
},
}
}
fn header(self: Format) ?[]const u8 {
return switch (self) {
.plaintext => null,
.markdown =>
\\---
\\title: Keybinding Action Reference
\\description: Reference of all Ghostty keybinding actions.
\\editOnGithubLink: https://github.com/ghostty-org/ghostty/edit/main/src/input/Binding.zig
\\---
\\
\\This is a reference of all Ghostty keybinding actions.
\\
\\
,
};
}
};
/// Generate keybind actions documentation with the specified format
pub fn generate(
writer: anytype,
format: Format,
page_allocator: std.mem.Allocator,
) !void {
if (format.header()) |header| {
try writer.writeAll(header);
}
var buffer = std.ArrayList(u8).init(page_allocator);
defer buffer.deinit();
const fields = @typeInfo(KeybindAction).Union.fields;
inline for (fields) |field| {
if (field.name[0] == '_') continue;
// Write previously stored doc comment below all related actions
if (@hasDecl(help_strings.KeybindAction, field.name)) {
try writer.writeAll(buffer.items);
try writer.writeAll("\n");
buffer.clearRetainingCapacity();
}
try format.formatFieldName(writer, field.name);
if (@hasDecl(help_strings.KeybindAction, field.name)) {
var iter = std.mem.splitScalar(
u8,
@field(help_strings.KeybindAction, field.name),
'\n',
);
while (iter.next()) |s| {
// If it is the last line and empty, then skip it.
if (iter.peek() == null and s.len == 0) continue;
try format.formatDocLine(&buffer, s);
}
}
}
// Write any remaining buffered documentation
if (buffer.items.len > 0) {
try writer.writeAll(buffer.items);
}
}