From b5676a53eeddc208f8ab8bb2008dbdb6c77e4453 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Fri, 4 Feb 2022 18:24:39 +0530 Subject: [PATCH] Use a special role for actions documentation --- docs/changelog.rst | 6 +++--- docs/conf.py | 19 +++++++++++++++++++ docs/kittens/custom.rst | 2 +- docs/shell-integration.rst | 2 +- kitty/actions.py | 5 +---- kitty/conf/types.py | 3 +++ kitty/options/definition.py | 4 ++-- 7 files changed, 30 insertions(+), 11 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 75c84d64d..f27f28ada 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -83,7 +83,7 @@ Detailed list of changes - ssh kitten: Fix location of generated terminfo files on NetBSD (:iss:`4622`) - A new action to clear the screen up to the line containing the cursor, see - :ref:`action-clear_terminal` + :ac:`clear_terminal` - macOS: Fix a regression in the previous release that broke switching input sources by keyboard (:iss:`4621`) @@ -153,7 +153,7 @@ Detailed list of changes - Fix getting last command output not working correctly when the screen is scrolled (:pull:`4522`) -- Show number of windows per tab in the :ref:`action-select_tab` action (:pull:`4523`) +- Show number of windows per tab in the :ac:`select_tab` action (:pull:`4523`) - macOS: Fix the shift key not clearing pre-edit text in IME (:iss:`4541`) @@ -438,7 +438,7 @@ Detailed list of changes 0.22.0 [2021-07-26] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Add a new :ref:`action-toggle_layout` action to easily zoom/unzoom a window +- Add a new :ac:`toggle_layout` action to easily zoom/unzoom a window - When right clicking to extend a selection, move the nearest selection boundary rather than the end of the selection. To restore previous behavior diff --git a/docs/conf.py b/docs/conf.py index c0a95b913..a0f8e0ad1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -399,6 +399,12 @@ def parse_shortcut_node(env: Any, sig: str, signode: Any) -> str: return sig +def parse_action_node(env: Any, sig: str, signode: Any) -> str: + """Transform an action description into RST nodes.""" + signode += addnodes.desc_name(sig, sig) + return sig + + def process_opt_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]: conf_name, opt = target.partition('.')[::2] if not opt: @@ -407,6 +413,10 @@ def process_opt_link(env: Any, refnode: Any, has_explicit_title: bool, title: st return title, opt_aliases.get(full_name, full_name) +def process_action_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]: + return title, target + + def process_shortcut_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]: conf_name, slug = target.partition('.')[::2] if not slug: @@ -444,6 +454,15 @@ def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None: sc_role.process_link = process_shortcut_link shortcut_slugs.clear() + app.add_object_type( + 'action', 'ac', + indextemplate="pair: %s; Action", + parse_node=parse_action_node, + ) + ac_role = app.registry.domain_roles['std']['ac'] + ac_role.warn_dangling = True + ac_role.process_link = process_action_link + def generate_default_config(definition: Definition, name: str) -> None: with open(f'generated/conf-{name}.rst', 'w', encoding='utf-8') as f: print('.. highlight:: conf\n', file=f) diff --git a/docs/kittens/custom.rst b/docs/kittens/custom.rst index d9fdacb98..12f74ba43 100644 --- a/docs/kittens/custom.rst +++ b/docs/kittens/custom.rst @@ -134,7 +134,7 @@ terminal program, you can tell the kittens system to run the For example, here is a kitten that "zooms/unzooms" the current terminal window by switching to the stack layout or back to the previous layout. This is -equivalent to the builtin :ref:`action-toggle_layout` action. +equivalent to the builtin :ac:`toggle_layout` action. Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py` diff --git a/docs/shell-integration.rst b/docs/shell-integration.rst index 3d4b2ca37..14d398346 100644 --- a/docs/shell-integration.rst +++ b/docs/shell-integration.rst @@ -93,7 +93,7 @@ to be copied. The feature to jump to previous prompts ( :sc:`scroll_to_previous_prompt` and :sc:`scroll_to_next_prompt`) and mouse -actions (:ref:`action-mouse_select_command_output` and :ref:`action-mouse_show_command_output`) can +actions (:ac:`mouse_select_command_output` and :ac:`mouse_show_command_output`) can be integrated with browsing command output as well. For example, define the following mapping in :file:`kitty.conf`: diff --git a/kitty/actions.py b/kitty/actions.py index ea306b5a3..87caef884 100644 --- a/kitty/actions.py +++ b/kitty/actions.py @@ -99,10 +99,7 @@ def as_rst() -> str: for action in allg[group]: a('') - a(f'.. _action-{action.name}:') - a('') - a(action.name) - a('+' * len(action.name)) + a(f'.. action:: {action.name}') a('') a(action.short_help) a('') diff --git a/kitty/conf/types.py b/kitty/conf/types.py index 774d666b3..46b2d5842 100644 --- a/kitty/conf/types.py +++ b/kitty/conf/types.py @@ -66,6 +66,9 @@ def remove_markup(text: str) -> str: if m.group(1) == 'ref': q = m.group(2).split('<')[-1].rstrip('>') return ref_map()[q] + if m.group(1) == 'ac': + q = m.group(2).split('<')[-1].rstrip('>') + return ref_map()[f'action-{q}'] return str(m.group(2)) return re.sub(r':([a-zA-Z0-9]+):`(.+?)`', sub, text, flags=re.DOTALL) diff --git a/kitty/options/definition.py b/kitty/options/definition.py index 4294b926b..ea453812f 100644 --- a/kitty/options/definition.py +++ b/kitty/options/definition.py @@ -947,7 +947,7 @@ windows, via the quit action). Negative values are converted to positive ones, however, with :ref:`shell_integration` enabled, using negative values means windows sitting at a shell prompt are not counted, only windows where some command is currently running. Note that if you want confirmation when closing -individual windows, you can map the :ref:`action-close_window_with_confirmation` action. +individual windows, you can map the :ac:`close_window_with_confirmation` action. ''' ) egr() # }}} @@ -998,7 +998,7 @@ The tab bar style, can be one of: :disc:`this discussion <4447>` for examples from kitty users. :code:`hidden` The tab bar is hidden. If you use this, you might want to create a - mapping for the :ref:`action-select_tab` + mapping for the :ac:`select_tab` action which presents you with a list of tabs and allows for easy switching to a tab. '''