Use a special role for actions documentation

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

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)

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`
 

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

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('')

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)

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