From 620782aa803115fc42e7af32f782defccab9f44b Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Sat, 2 Jun 2018 14:45:46 +0530
Subject: [PATCH] Document the icat kitten

---
 docs/index.rst        |  4 ++++
 docs/kittens/icat.rst | 29 +++++++++++++++++++++++++++++
 kittens/icat/main.py  | 16 ++++++++++++----
 3 files changed, 45 insertions(+), 4 deletions(-)
 create mode 100644 docs/kittens/icat.rst

diff --git a/docs/index.rst b/docs/index.rst
index 955a6475c..cf898ef8a 100644
--- a/docs/index.rst
+++ b/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 
diff --git a/docs/kittens/icat.rst b/docs/kittens/icat.rst
new file mode 100644
index 000000000..8d9ea700c
--- /dev/null
+++ b/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
diff --git a/kittens/icat/main.py b/kittens/icat/main.py
index 427c18bce..23bdee78e 100755
--- a/kittens/icat/main.py
+++ b/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):
-    msg = (
+help_text = (
         '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.')
-    args, items = parse_args(args[1:], options_spec, 'image-file ...', msg, '{} icat'.format(appname))
+        ' Directories are scanned recursively for image files.'
+)
+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