Merge branch 'docs-shortcuts' of https://github.com/page-down/kitty

docs/actions.rst

@@ -4,6 +4,7 @@ Mappable actions
 .. highlight:: conf
 
 The actions described below can be mapped to any key press or mouse action
-using the ``map`` and ``mouse_map`` directives in :file:`kitty.conf`.
+using the ``map`` and ``mouse_map`` directives in :file:`kitty.conf`. For
+configuration examples, see the default shortcut links for each action.
 
 .. include:: /generated/actions.rst

docs/kittens/hints.rst

@@ -36,7 +36,7 @@ taken for different types of URLs <../open_actions>`.
 The hints kitten is very powerful to see more detailed help on its various
 options and modes of operation, see below. You can use these options to
 create mappings in :file:`kitty.conf` to select various different text
-snippets. See :sc:`insert_selected_path` for examples.
+snippets. See :sc:`insert_selected_path <insert_selected_path>` for examples.
 
 
 Completely customizing the matching and actions of the kitten

docs/overview.rst

@@ -244,15 +244,15 @@ for example::
    map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R
 
 Would open the scrollback buffer in a new :term:`window` when you press the :kbd:`F1`
-key. See :sc:`show_scrollback` for details.
+key. See :sc:`show_scrollback <show_scrollback>` for details.
 
 If you want to use it with an editor such as vim to get more powerful features,
 you can see tips for doing so, in
 `this thread <https://github.com/kovidgoyal/kitty/issues/719>`_.
 
 If you wish to store very large amounts of scrollback to view using the piping or
-:sc:`show_scrollback` features, you can use the :opt:`scrollback_pager_history_size`
+:sc:`show_scrollback <show_scrollback>` features, you can use the
-option.
+:opt:`scrollback_pager_history_size` option.
 
 
 Integration with shells

kitty/actions.py

@@ -84,6 +84,10 @@ def as_rst() -> str:
     def key(x: ActionGroup) -> str:
         return group_title(x).lower()
 
+    def kitten_link(text: str) -> str:
+        x = text.split()
+        return f':doc:`kittens/{x[2]}`'.replace('_', '-') if len(x) > 2 else ''
+
     for group in sorted(allg, key=key):
         title = group_title(group)
         a('')
@@ -107,6 +111,12 @@ def as_rst() -> str:
             if action.name in maps:
                 a('')
                 a('Default shortcuts using this action:')
-                scs = {f':sc:`kitty.{m.name}`' for m in maps[action.name]}
+                if action.name == 'kitten':
-                a(', '.join(sorted(scs)))
+                    scs = {(kitten_link(m.parseable_text), m.short_text, f':sc:`kitty.{m.name}`') for m in maps[action.name]}
+                    for s in sorted(scs):
+                        a('')
+                        a(f'- {s[0]} - {s[2]} {s[1]}')
+                else:
+                    scs = {f':sc:`kitty.{m.name}`' for m in maps[action.name]}
+                    a(', '.join(sorted(scs)))
     return '\n'.join(lines)

kitty/boss.py

@@ -749,7 +749,7 @@ class Boss:
     @ac('misc', '''
         Clear the terminal
 
-        See :sc:`reset_terminal` for details. For example::
+        See :sc:`reset_terminal <reset_terminal>` for details. For example::
 
             # Reset the terminal
             map kitty_mod+f9 clear_terminal reset active

kitty/window.py

@@ -569,7 +569,7 @@ class Window:
     @ac('misc', '''
         Send the specified text to the active window
 
-        For details, see :sc:`send_text`.
+        See :sc:`send_text <send_text>` for details.
         ''')
     def send_text(self, *args: str) -> bool:
         mode = keyboard_mode_name(self.screen)