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

docs/faq.rst

@@ -312,7 +312,10 @@ the :sc:`send_text <send_text>` you can use the ``show_key`` kitten. Run::
 Then press the key you want to emulate. Note that this kitten will only show
 keys that actually reach the terminal program, in particular, keys mapped to
 actions in kitty will not be shown. To check those first map them to
-:ac:`no_op`.
+:ac:`no_op`. You can also start a kitty instance without any shortcut configuration::
+
+    kitty -o clear_all_shortcuts=yes kitty +kitten show_key
+
 
 How do I open a new window or tab with the same working directory as the current window?
 --------------------------------------------------------------------------------------------

kitty/cli.py

@@ -293,7 +293,7 @@ def parse_option_spec(spec: Optional[str] = None) -> Tuple[OptionSpecSeq, Option
             else:
                 prev_indent = 0
                 if prev_line:
-                    current_cmd['help'] += '\n\n'
+                    current_cmd['help'] += '\n' if current_cmd['help'].endswith('::') else '\n\n'
                 else:
                     state = NORMAL
                     (seq if current_cmd.get('condition', True) else disabled).append(current_cmd)
@@ -429,6 +429,8 @@ class PrintHelpForSeq:
         a('{}: {} {}{}'.format(title('Usage'), bold(yellow(appname)), optstring, usage))
         a('')
         message = message or default_msg
+        # replace rst literal code block syntax
+        message = message.replace('::\n\n', ':\n\n')
         wa(prettify(message))
         a('')
         if seq:
@@ -448,6 +450,8 @@ class PrintHelpForSeq:
                     blocks[-1] += dt
             if opt.get('help'):
                 t = help_text.replace('%default', str(defval)).strip()
+                # replace rst literal code block syntax
+                t = t.replace('::\n\n', ':\n\n')
                 t = t.replace('#placeholder_for_formatting#', '')
                 wa(prettify(t), indent=4)
                 if opt.get('choices'):
@@ -801,6 +805,7 @@ Output commands received from child process to STDOUT.
 Replay previously dumped commands. Specify the path to a dump file previously
 created by :option:`{appname} --dump-commands`. You
 can open a new kitty window to replay the commands with::
+
     {appname} sh -c "{appname} --replay-commands /path/to/dump/file; read"
 
 

kitty/launch.py

@@ -165,12 +165,14 @@ type=list
 Restrict the actions remote control is allowed to take. This works like
 :opt:`remote_control_password`. You can specify a password and list of actions
 just as for :opt:`remote_control_password`. For example::
+
     --remote-control-password '"my passphrase" get-* set-colors'
 
 This password will be in effect for this window only.
 Note that any passwords you have defined for :opt:`remote_control_password`
 in :file:`kitty.conf` are also in effect. You can override them by using the same password here.
 You can also disable all :opt:`remote_control_password` global passwords for this window, by using::
+
     --remote-control-password '!'
 
 This option only takes effect if :option:`--allow-remote-control`
@@ -271,8 +273,9 @@ effect if :option:`--logo` is specified. See :opt:`window_logo_alpha`.
 type=list
 Change colors in the newly launched window. You can either specify a path to a
 :file:`.conf` file with the same syntax as :file:`kitty.conf` to read the colors
-from, or specify them individually, for example: :code:`--color background=white
---color foreground=red`.
+from, or specify them individually, for example::
+
+    --color background=white --color foreground=red
 
 
 --watcher -w

kitty/rc/launch.py

@@ -53,8 +53,8 @@ class Launch(RemoteCommand):
     desc = (
         'Prints out the id of the newly opened window. Any command line arguments'
         ' are assumed to be the command line used to run in the new window, if none'
-        ' are provided, the default shell is run. For example:\n'
-        ':code:`kitty @ launch --title=Email mutt`'
+        ' are provided, the default shell is run. For example::\n\n'
+        '    kitty @ launch --title=Email mutt'
     )
     options_spec = MATCH_TAB_OPTION + '\n\n' + '''\
 --no-response

kitty/rc/new_window.py

@@ -34,8 +34,8 @@ class NewWindow(RemoteCommand):
         ' Prints out the id of the newly opened window'
         ' (unless :option:`--no-response` is used). Any command line arguments'
         ' are assumed to be the command line used to run in the new window, if none'
-        ' are provided, the default shell is run. For example:\n'
-        ':code:`kitty @ new-window --title Email mutt`'
+        ' are provided, the default shell is run. For example::\n\n'
+        '    kitty @ new-window --title Email mutt'
     )
     options_spec = MATCH_TAB_OPTION + '''\n
 --title

kitty/rc/set_background_opacity.py

@@ -27,7 +27,8 @@ class SetBackgroundOpacity(RemoteCommand):
     desc = (
         'Set the background opacity for the specified windows. This will only work if you have turned on'
         ' :opt:`dynamic_background_opacity` in :file:`kitty.conf`. The background opacity affects all kitty windows in a'
-        ' single OS window. For example: :code:`kitty @ set-background-opacity 0.5`'
+        ' single OS window. For example::\n\n'
+        '    kitty @ set-background-opacity 0.5'
     )
     options_spec = '''\
 --all -a

kitty/rc/set_colors.py

@@ -68,7 +68,8 @@ class SetColors(RemoteCommand):
         'Set the terminal colors for the specified windows/tabs (defaults to active window).'
         ' You can either specify the path to a conf file'
         ' (in the same format as :file:`kitty.conf`) to read the colors from or you can specify individual colors,'
-        ' for example: :code:`kitty @ set-colors foreground=red background=white`'
+        ' for example::\n\n'
+        '    kitty @ set-colors foreground=red background=white'
     )
     options_spec = '''\
 --all -a