More conf docs

Add a 🔗 role that works nicely in both contexts

docs/conf.py

@@ -306,6 +306,18 @@ def write_cli_docs():
 
 # config file docs {{{
 
+def link_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    m = re.match(r'(.+)\s+<(.+?)>', text)
+    if m is None:
+        msg = inliner.reporter.error(f'link "{text}" not recognized', line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    text, url = m.group(1, 2)
+    set_classes(options)
+    node = nodes.reference(rawtext, text, refuri=url, **options)
+    return [node], []
+
+
 def render_group(a, group):
     a(group.short_text)
     heading_level = '+' if '.' in group.name else '^'
@@ -417,6 +429,7 @@ def setup(app):
         pass
     write_cli_docs()
     write_conf_docs(app)
+    app.add_role('link', link_role)
     app.add_role('iss', partial(num_role, 'issues'))
     app.add_role('pull', partial(num_role, 'pull'))
     app.add_role('commit', commit_role)

kitty/conf/definition.py

@@ -85,7 +85,7 @@ def merged_opts(all_options, opt, i):
 
 
 def remove_markup(text):
-    return re.sub(r':(.+?):`(.+?)`', r'\2', text, flags=re.DOTALL)
+    return re.sub(r':([a-zA-Z0-9]+):`(.+?)`', r'\2', text, flags=re.DOTALL)
 
 
 def render_block(text):

kitty/config.py

@@ -13,13 +13,13 @@ from . import fast_data_types as defines
 from .conf.definition import as_conf_file
 from .conf.utils import (
     init_config, key_func, load_config as _load_config, merge_dicts,
-    parse_config_base, positive_int, python_string, to_bool,
+    parse_config_base, python_string, to_bool,
     to_cmdline
 )
 from .config_data import all_options
 from .constants import cache_dir, defconf
 from .utils import log_error
-from .config_data import to_modifiers, parse_mods
+from .config_data import parse_mods, type_map
 
 
 named_keys = {
@@ -246,25 +246,6 @@ def parse_send_text(val, key_definitions):
     return parse_key(key_str, key_definitions)
 
 
-type_map = {
-    'allow_remote_control': to_bool,
-    'focus_follows_mouse': to_bool,
-    'input_delay': positive_int,
-    'sync_to_monitor': to_bool,
-    'close_on_child_death': to_bool,
-    'enable_audio_bell': to_bool,
-    'remember_window_size': to_bool,
-    'macos_hide_titlebar': to_bool,
-    'macos_hide_from_tasks': to_bool,
-    'macos_option_as_alt': to_bool,
-    'dynamic_background_opacity': to_bool,
-    'window_alert_on_bell': to_bool,
-    'bell_on_tab': to_bool,
-    'kitty_mod': to_modifiers,
-    'clear_all_shortcuts': to_bool,
-}
-
-
 def special_handling(key, val, ans):
     if key == 'map':
         parse_key(val, ans['key_definitions'])

kitty/config_data.py

@@ -139,8 +139,36 @@ as color16 to color256.''')
     ],
     'advanced': [_('Advanced')],
     'os': [_('OS specific tweaks')],
+    'shortcuts': [
+        _('Keyboard shortcuts'),
+        _('''\
+For a list of key names, see: :link:`GLFW keys <http://www.glfw.org/docs/latest/group__keys.html>`
+For a list of modifier names, see: :link:`GLFW mods <http://www.glfw.org/docs/latest/group__mods.html>`
+
+You can use the special action :code:`no_op` to unmap a keyboard shortcut that is
+assigned in the default configuration.
+
+You can combine multiple actions to be triggered by a single shortcut, using the
+syntax below::
+
+    map key combine <separator> action1 <separator> action2 <separator> action3 ...
+
+For example::
+
+    map kitty_mod+e combine : new_window : next_layout
+
+this will create a new window and switch to the next available layout
+
+You can use multi-key shortcuts using the syntax shown below::
+
+    map key1>key2>key3 action
+
+For example::
+
+    map ctrl+f>2 set_font_size 20
+''')
+    ],
 })
-type_map = {o.name: o.option_type for o in all_options.values()}
 # }}}
 
 g('fonts')  # {{{
@@ -569,3 +597,12 @@ Hide the kitty window from running tasks (:kbd:`Option+Tab`) on macOS.
 
 
 # }}}
+
+g('shortcuts')  # {{
+o('kitty_mod', 'ctrl+shift', option_type=to_modifiers, long_text=_('''
+The value of :code:`kitty_mod` is used as the modifier for all default shortcuts, you
+can change it in your kitty.conf to change the modifiers for all the default
+shortcuts.'''))
+# }}}
+
+type_map = {o.name: o.option_type for o in all_options.values()}