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/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.
 '''
     )