Add CLI docs for the hints kitten

docs/kittens/hints.rst

@@ -19,8 +19,9 @@ terminal, very useful for picking files from the output of a ``git`` or ``ls`` c
 adding them to the command line for the next command.
 
 The hints kitten is very powerful to see more detailed help on its various
-options and modes of operation, use::
-
-    kitty +kitten hints --help
+options and modes of operation, see below.
 
+Command Line Interface
+-------------------------
 
+.. include:: ../generated/cli-kitten-hints.rst

kittens/hints/main.py

@@ -6,7 +6,7 @@
 import re
 import string
 import sys
-from functools import lru_cache, partial
+from functools import lru_cache
 from gettext import gettext as _
 from itertools import repeat
 
@@ -303,12 +303,12 @@ def run(args, text):
 
 
 # CLI {{{
-OPTIONS = partial(r'''
+OPTIONS = r'''
 --program
 default=default
 What program to use to open matched text. Defaults to the default open program
-for the operating system.  Use a value of - to paste the match into the
-terminal window instead. A value of @ will copy the match to the clipboard.
+for the operating system.  Use a value of :file:`-` to paste the match into the
+terminal window instead. A value of :file:`@` will copy the match to the clipboard.
 
 
 --type
@@ -319,9 +319,10 @@ def run(args, text):
 
 --regex
 default=(?m)^\s*(.+)\s*$
-The regular expression to use when --type=regex.  If you specify a group in the
-regular expression only the group will be matched. This allow you to match text
-ignoring a prefix/suffix, as needed. The default expression matches lines.
+The regular expression to use when :option:`kitty +kitten hints --type`=regex.
+If you specify a group in the regular expression only the group
+will be matched. This allow you to match text ignoring a prefix/suffix, as
+needed. The default expression matches lines.
 
 
 --url-prefixes
@@ -339,12 +340,13 @@ def run(args, text):
 default=3
 type=int
 The minimum number of characters to consider a match.
-'''.format, ','.join(sorted(URL_PREFIXES)))
+'''.format(','.join(sorted(URL_PREFIXES))).format
+help_text = 'Select text from the screen using the keyboard. Defaults to searching for URLs.'
+usage = ''
 
 
 def parse_hints_args(args):
-    msg = 'Select text from the screen using the keyboard. Defaults to searching for URLs.'
-    return parse_args(args, OPTIONS, '', msg, 'hints')
+    return parse_args(args, OPTIONS, usage, help_text, 'kitty +kitten hints')
 
 
 def main(args):
@@ -395,4 +397,8 @@ def handle_result(args, data, target_window_id, boss):
     ans = main(sys.argv)
     if ans:
         print(ans)
+elif __name__ == '__doc__':
+    sys.cli_docs['usage'] = usage
+    sys.cli_docs['options'] = OPTIONS
+    sys.cli_docs['help_text'] = help_text
 # }}}

kitty/cli.py

@@ -189,10 +189,17 @@ def title(x):
 
 
 def option(x):
+    idx = x.find('-')
+    if idx > -1:
+        x = x[idx:]
     parts = map(bold, x.split())
     return ' '.join(parts)
 
 
+def code(x):
+    return x
+
+
 def env(x):
     return italic(x)
 
@@ -267,7 +274,7 @@ def sub(m):
 
 
 def prettify_rst(text):
-    return text
+    return re.sub(r':([a-z]+):`([^`]+)`(=[^\s.]+)', r':\1:`\2`:code:`\3`', text)
 
 
 def version(add_rev=False):
@@ -419,9 +426,9 @@ def seq_as_rst(seq, usage, message, appname, heading_char='-'):
             a('')
             a(textwrap.indent(prettify_rst(t), ' ' * 4))
             if defval is not None:
-                a(textwrap.indent('Default: {}'.format(defval), ' ' * 4))
+                a(textwrap.indent('Default: :code:`{}`'.format(defval), ' ' * 4))
             if 'choices' in opt:
-                a(textwrap.indent('Choices: {}'.format(', '.join(opt['choices'])), ' ' * 4))
+                a(textwrap.indent('Choices: :code:`{}`'.format(', '.join(opt['choices'])), ' ' * 4))
             a('')
 
     text = '\n'.join(blocks)