Docs: Improve the documentation for kittens

Add more text roles and links.
Add an example that broadcasts only to other windows in the current tab.
Initial capitalization of the key names in the kbd text role.
Add Python type hints for custom kittens.
Note about hyperlink support for ls on macOS.
Add description text for show_key.

kittens/ask/main.py

@@ -92,17 +92,17 @@ be used for completions and via the browse history readline bindings.
 --choice -c
 type=list
 dest=choices
-A choice for the choices type. Every choice has the syntax: letter:text Where
-letter is the accelerator key and text is the corresponding text.  There can be
-an optional color specification after the letter to indicate what color it should
-be.
-For example: y:Yes and n;red:No
+A choice for the choices type. Can be specified multiple times. Every choice has
+the syntax: ``letter[;color]:text``. Where :italic:`letter` is the accelerator key
+and :italic:`text` is the corresponding text. There can be an optional color
+specification after the letter to indicate what color it should be.
+For example: :code:`y:Yes` and :code:`n;red:No`
 
 
 --default -d
-A default choice or text. If unspecified, it is "y" for :code:`yesno`, the first choice
-for :code:`choices` and empty for others. The default choice is selected when the user
-presses the Enter key.
+A default choice or text. If unspecified, it is :code:`y` for the type
+:code:`yesno`, the first choice for :code:`choices` and empty for others types.
+The default choice is selected when the user presses the :kbd:`Enter` key.
 
 
 --prompt -p
@@ -406,7 +406,7 @@ def main(args: List[str]) -> Response:
     except SystemExit as e:
         if e.code != 0:
             print(e.args[0])
-            input('Press enter to quit...')
+            input('Press Enter to quit')
         raise SystemExit(e.code)
 
     if cli_opts.type in ('yesno', 'choices'):

kittens/broadcast/main.py

@@ -99,7 +99,7 @@ class Broadcast(Handler):
 
 
 OPTIONS = (MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t')).format
-help_text = 'Broadcast typed text to all kitty windows. By default text is sent to all windows, unless one of the matching options is specified'
+help_text = 'Broadcast typed text to kitty windows. By default text is sent to all windows, unless one of the matching options is specified'
 usage = '[initial text to send ...]'
 
 

kittens/diff/main.py

@@ -571,8 +571,8 @@ OPTIONS = partial('''\
 --context
 type=int
 default=-1
-Number of lines of context to show between changes. Negative values
-use the number set in diff.conf
+Number of lines of context to show between changes. Negative values use the
+number set in :file:`diff.conf`.
 
 
 --config
@@ -599,7 +599,7 @@ class ShowWarning:
 
 
 showwarning = ShowWarning()
-help_text = 'Show a side-by-side diff of the specified files/directories. You can also use ssh:hostname:remote-file-path to diff remote files.'
+help_text = 'Show a side-by-side diff of the specified files/directories. You can also use :italic:`ssh:hostname:remote-file-path` to diff remote files.'
 usage = 'file_or_directory_left file_or_directory_right'
 
 

kittens/diff/options/definition.py

@@ -24,8 +24,8 @@ agr('diff', 'Diffing')
 opt('syntax_aliases', 'pyj:py pyi:py recipe:py',
     option_type='syntax_aliases',
     long_text='''
-File extension aliases for syntax highlight For example, to syntax highlight
-:file:`file.xyz` as :file:`file.abc` use a setting of :code:`xyz:abc`
+File extension aliases for syntax highlight. For example, to syntax highlight
+:file:`file.xyz` as :file:`file.abc` use a setting of :code:`xyz:abc`.
 '''
     )
 
@@ -38,7 +38,7 @@ opt('diff_cmd', 'auto',
     long_text='''
 The diff command to use. Must contain the placeholder :code:`_CONTEXT_` which
 will be replaced by the number of lines of context. The default is to search the
-system for either git or diff and use that, if found.
+system for either :program:`git` or :program:`diff` and use that, if found.
 '''
     )
 

kittens/icat/main.py

@@ -42,24 +42,24 @@ Horizontal alignment for the displayed image.
 
 
 --place
-Choose where on the screen to display the image. The image will
-be scaled to fit into the specified rectangle. The syntax for
-specifying rectangles is <:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>.
-All measurements are in cells (i.e. cursor positions) with the
-origin :italic:`(0, 0)` at the top-left corner of the screen.
+Choose where on the screen to display the image. The image will be scaled to fit
+into the specified rectangle. The syntax for specifying rectangles is
+<:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>.
+All measurements are in cells (i.e. cursor positions) with the origin
+:italic:`(0, 0)` at the top-left corner of the screen.
 
 
 --scale-up
 type=bool-set
-When used in combination with :option:`--place` it will cause images that
-are smaller than the specified area to be scaled up to use as much
-of the specified area as possible.
+When used in combination with :option:`--place` it will cause images that are
+smaller than the specified area to be scaled up to use as much of the specified
+area as possible.
 
 
 --background
 default=none
-Specify a background color, this will cause transparent images to be composited on
-top of the specified color.
+Specify a background color, this will cause transparent images to be composited
+on top of the specified color.
 
 
 --mirror
@@ -79,17 +79,18 @@ type=choices
 choices=detect,file,stream
 default=detect
 Which mechanism to use to transfer images to the terminal. The default is to
-auto-detect. :italic:`file` means to use a temporary file and :italic:`stream` means to
-send the data via terminal escape codes. Note that if you use the :italic:`file`
-transfer mode and you are connecting over a remote session then image display
-will not work.
+auto-detect. :italic:`file` means to use a temporary file and :italic:`stream`
+means to send the data via terminal escape codes. Note that if you use the
+:italic:`file` transfer mode and you are connecting over a remote session then
+image display will not work.
 
 
 --detect-support
 type=bool-set
 Detect support for image display in the terminal. If not supported, will exit
 with exit code 1, otherwise will exit with code 0 and print the supported
-transfer mode to stderr, which can be used with the :option:`--transfer-mode` option.
+transfer mode to stderr, which can be used with the :option:`--transfer-mode`
+option.
 
 
 --detection-timeout
@@ -101,17 +102,17 @@ detecting image display support.
 
 --print-window-size
 type=bool-set
-Print out the window size as :italic:`widthxheight` (in pixels) and quit. This is a
-convenience method to query the window size if using :code:`kitty +kitten icat` from a
-scripting language that cannot make termios calls.
+Print out the window size as <:italic:`width`>x<:italic:`height`> (in pixels) and quit. This is a
+convenience method to query the window size if using :code:`kitty +kitten icat`
+from a scripting language that cannot make termios calls.
 
 
 --stdin
 type=choices
 choices=detect,yes,no
 default=detect
-Read image data from stdin. The default is to do it automatically, when STDIN is not a terminal,
-but you can turn it off or on explicitly, if needed.
+Read image data from STDIN. The default is to do it automatically, when STDIN is
+not a terminal, but you can turn it off or on explicitly, if needed.
 
 
 --silent
@@ -121,9 +122,9 @@ Do not print out anything to STDOUT during operation.
 
 --z-index -z
 default=0
-Z-index of the image. When negative, text will be displayed on top of the image. Use
-a double minus for values under the threshold for drawing images under cell background
-colors. For example, :code:`--1` evaluates as -1,073,741,825.
+Z-index of the image. When negative, text will be displayed on top of the image.
+Use a double minus for values under the threshold for drawing images under cell
+background colors. For example, :code:`--1` evaluates as -1,073,741,825.
 
 
 --loop -l

kittens/query_terminal/main.py

@@ -66,7 +66,7 @@ def query(cls: Type[Query]) -> Type[Query]:
 class TerminalName(Query):
     name: str = 'name'
     override_query_name: str = 'name'
-    help_text: str = f'Terminal name ({names[0]})'
+    help_text: str = f'Terminal name (e.g. :code:`{names[0]}`)'
 
     @staticmethod
     def get_result(opts: Options) -> str:
@@ -76,7 +76,7 @@ class TerminalName(Query):
 @query
 class TerminalVersion(Query):
     name: str = 'version'
-    help_text: str = 'Terminal version, for e.g.: 0.19.2'
+    help_text: str = f'Terminal version (e.g. :code:`{str_version}`)'
 
     @staticmethod
     def get_result(opts: Options) -> str:
@@ -86,7 +86,7 @@ class TerminalVersion(Query):
 @query
 class AllowHyperlinks(Query):
     name: str = 'allow_hyperlinks'
-    help_text: str = 'The :opt:`setting <allow_hyperlinks>` for allowing hyperlinks can be yes, no or ask'
+    help_text: str = 'The :opt:`setting <allow_hyperlinks>` for allowing hyperlinks can be :code:`yes`, :code:`no` or :code:`ask`'
 
     @staticmethod
     def get_result(opts: Options) -> str:
@@ -154,7 +154,7 @@ class FontSize(Query):
 @query
 class ClipboardControl(Query):
     name: str = 'clipboard_control'
-    help_text: str = 'The :opt:`setting <clipboard_control>` for allowing reads/writes to/from the clipboard'
+    help_text: str = 'The config option :opt:`clipboard_control` in :file:`kitty.conf` for allowing reads/writes to/from the clipboard'
 
     @staticmethod
     def get_result(opts: Options) -> str:
@@ -200,30 +200,28 @@ querying it.
 
 
 help_text = '''\
-Query the terminal this kitten is run in for various
-capabilities. This sends escape codes to the terminal
-and based on its response prints out data about supported
-capabilities. Note that this is a blocking operation, since
-it has to wait for a response from the terminal. You can control
-the maximum wait time via the ``--wait-for`` option.
+Query the terminal this kitten is run in for various capabilities. This sends
+escape codes to the terminal and based on its response prints out data about
+supported capabilities. Note that this is a blocking operation, since it has to
+wait for a response from the terminal. You can control the maximum wait time via
+the :code:`--wait-for` option.
 
 The output is lines of the form::
 
-  query: data
+    :italic:`query`: :italic:`data`
 
-If a particular query is unsupported by the running kitty version,
-the data will be blank.
+If a particular query is unsupported by the running kitty version, the data will
+be blank.
 
-Note that when calling this from another program, be very
-careful not to perform any I/O on the terminal device
-until the kitten exits.
+Note that when calling this from another program, be very careful not to perform
+any I/O on the terminal device until thos kitten exits.
 
 Available queries are:
 
 {}
 
 '''.format('\n'.join(
-    f'``{name}``\n  {c.help_text}\n' for name, c in all_queries.items()))
+    f':code:`{name}`:\n  {c.help_text}\n' for name, c in all_queries.items()))
 usage = '[query1 query2 ...]'
 
 

kittens/remote_file/main.py

@@ -55,7 +55,7 @@ The data used to connect over ssh.
 def show_error(msg: str) -> None:
     print(styled(msg, fg='red'))
     print()
-    print('Press any key to exit...')
+    print('Press any key to quit')
     sys.stdout.flush()
     with raw_mode():
         while True:
@@ -208,7 +208,7 @@ def main(args: List[str]) -> Result:
     except SystemExit as e:
         if e.code != 0:
             print(e.args[0])
-            input('Press enter to quit...')
+            input('Press Enter to quit')
         raise SystemExit(e.code)
 
     try:
@@ -236,7 +236,7 @@ def save_as(conn_data: SSHConnectionData, remote_path: str, cli_opts: RemoteFile
         last_used_path = tempfile.gettempdir()
     last_used_file = os.path.join(last_used_path, os.path.basename(remote_path))
     print(
-        'Where do you wish to save the file? Leaving it blank will save it as:',
+        'Where do you want to save the file? Leaving it blank will save it as:',
         styled(last_used_file, fg='yellow')
     )
     print('Relative paths will be resolved from:', styled(os.getcwd(), fg_intense=True, bold=True))

kittens/runner.py

@@ -175,4 +175,4 @@ def main() -> None:
         print('Unhandled exception running kitten:')
         import traceback
         traceback.print_exc()
-        input('Press Enter to quit...')
+        input('Press Enter to quit')

kittens/show_key/main.py

@@ -57,13 +57,15 @@ OPTIONS = r'''
 default=normal
 type=choices
 choices=normal,application,kitty,unchanged
-The keyboard mode to use when showing keys. "normal" mode is with DECCKM reset and "application" mode is with
-DECCKM set. "kitty" is the full kitty extended keyboard protocol.
+The keyboard mode to use when showing keys. :code:`normal` mode is with DECCKM
+reset and :code:`application` mode is with DECCKM set. :code:`kitty` is the full
+kitty extended keyboard protocol.
 '''.format
+help_text = 'Show the codes generated by the terminal for key presses in various keyboard modes'
 
 
 def main(args: List[str]) -> None:
-    cli_opts, items = parse_args(args[1:], OPTIONS, '', '', 'kitty +kitten show_key', result_class=ShowKeyCLIOptions)
+    cli_opts, items = parse_args(args[1:], OPTIONS, '', help_text, 'kitty +kitten show_key', result_class=ShowKeyCLIOptions)
     if cli_opts.key_mode == 'kitty':
         from .kitty_mode import main as kitty_main
         return kitty_main()

kittens/transfer/main.py

@@ -35,26 +35,28 @@ destination path on the receiving computer.
 
 
 --permissions-bypass -p
-The password to use to skip the transfer confirmation popup in kitty. Must match the
-password set for the :opt:`file_transfer_confirmation_bypass` option in kitty.conf. Note that
-leading and trailing whitespace is removed from the password. A password starting with
-., / or ~ characters is assumed to be a file name to read the password from. A value
-of - means read the password from STDIN. A password that is purely a number less than 256
-is assumed to be the number of a file descriptor from which to read the actual password.
+The password to use to skip the transfer confirmation popup in kitty. Must match
+the password set for the :opt:`file_transfer_confirmation_bypass` option in
+:file:`kitty.conf`. Note that leading and trailing whitespace is removed from
+the password. A password starting with :code:`.`, :code:`/` or :code:`~`
+characters is assumed to be a file name to read the password from. A value of
+:code:`-` means read the password from STDIN. A password that is purely a number
+less than 256 is assumed to be the number of a file descriptor from which to
+read the actual password.
 
 
 --confirm-paths -c
 type=bool-set
-Before actually transferring files, show a mapping of local file names to remote file names
-and ask for confirmation.
+Before actually transferring files, show a mapping of local file names to remote
+file names and ask for confirmation.
 
 
 --transmit-deltas -x
 type=bool-set
-If a file on the receiving side already exists, use the rsync algorithm to update it to match
-the file on the sending side, potentially saving lots of bandwidth and also automatically resuming
-partial transfers. Note that this will actually degrade performance on fast links with small
-files, so use with care.
+If a file on the receiving side already exists, use the rsync algorithm to
+update it to match the file on the sending side, potentially saving lots of
+bandwidth and also automatically resuming partial transfers. Note that this will
+actually degrade performance on fast links with small files, so use with care.
 '''
 
 

kittens/unicode_input/main.py

@@ -546,7 +546,7 @@ class UnicodeInput(Handler):
         self.refresh()
 
 
-help_text = 'Input a unicode character'
+help_text = 'Input a Unicode character'
 usage = ''
 OPTIONS = '''
 --emoji-variation
@@ -554,7 +554,7 @@ type=choices
 default=none
 choices=none,graphic,text
 Whether to use the textual or the graphical form for emoji. By default the
-default form specified in the unicode standard for the symbol is used.
+default form specified in the Unicode standard for the symbol is used.
 
 
 '''.format