Document the icat kitten

docs/index.rst

@@ -225,6 +225,10 @@ its advanced features. These programs are called kittens. They are used both
 to add features to |kitty| itself and to create useful standalone programs.
 Some prominent kittens:
 
+:doc:`icat <kittens/icat>`
+    Display images in the terminal
+
+
 :doc:`diff <kittens/diff>`
     A fast, side-by-side diff for the terminal with syntax highlighting and
     images 

docs/kittens/icat.rst

@@ -0,0 +1,29 @@
+icat - Display images in the terminal
+========================================
+
+The ``icat`` kitten can be used to display arbitrary images in the |kitty|
+terminal. Using it is as simple as::
+
+    kitty +kitten icat image.jpeg
+
+It supports all image types supported by `ImageMagick
+<https://www.imagemagick.org>`_. It even works over SSH. For details, see
+the :doc:`kitty graphics protocol </graphics-protocol>`.
+
+.. note:: 
+
+    `ImageMagick <https://www.imagemagick.org>`_ must be installed for ``icat`` to
+    work.
+
+
+.. program:: kitty +kitten icat
+
+
+The ``icat`` kitten has various command line arguments to allow it to be used
+from inside other programs to display images. In particular, :option:`--place`,
+:option:`--detect-support` and :option:`--print-window-size`.
+
+Command Line Interface
+--------------------------
+
+.. include:: /generated/cli-kitten-icat.rst

kittens/icat/main.py

@@ -245,12 +245,16 @@ def parse_place(raw):
         return namedtuple('Place', 'width height left top')(w, h, l, t)
 
 
-def main(args=sys.argv):
+help_text = (
-    msg = (
         'A cat like utility to display images in the terminal.'
         ' You can specify multiple image files and/or directories.'
-        ' Directories are scanned recursively for image files.')
+        ' Directories are scanned recursively for image files.'
-    args, items = parse_args(args[1:], options_spec, 'image-file ...', msg, '{} icat'.format(appname))
+)
+usage = 'image-file ...'
+
+
+def main(args=sys.argv):
+    args, items = parse_args(args[1:], options_spec, usage, help_text, '{} +kitten icat'.format(appname))
 
     if args.print_window_size:
         screen_size_function.ans = None
@@ -320,3 +324,7 @@ def main(args=sys.argv):
 
 if __name__ == '__main__':
     main()
+elif __name__ == '__doc__':
+    sys.cli_docs['usage'] = usage
+    sys.cli_docs['options'] = options_spec
+    sys.cli_docs['help_text'] = help_text