From b98fca972f0c9c28f45d91f195e193a2432e8205 Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Mon, 4 Jun 2018 14:43:34 +0530
Subject: [PATCH] More conf docs

Add a :link: role that works nicely in both contexts
---
 docs/conf.py             | 13 +++++++++++++
 kitty/conf/definition.py |  2 +-
 kitty/config.py          | 23 ++---------------------
 kitty/config_data.py     | 39 ++++++++++++++++++++++++++++++++++++++-
 4 files changed, 54 insertions(+), 23 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 31ff80eac..8e5d844e0 100644
--- a/docs/conf.py
+++ b/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)
diff --git a/kitty/conf/definition.py b/kitty/conf/definition.py
index e63511c11..66b2ef9f4 100644
--- a/kitty/conf/definition.py
+++ b/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):
diff --git a/kitty/config.py b/kitty/config.py
index 31409b5d9..c7b31e8d0 100644
--- a/kitty/config.py
+++ b/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'])
diff --git a/kitty/config_data.py b/kitty/config_data.py
index 1cdba8376..3b3a1f60b 100644
--- a/kitty/config_data.py
+++ b/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()}