Document the clipboard kitten

docs/index.rst

@@ -246,6 +246,10 @@ Some prominent kittens:
     Draw a GPU accelerated dock panel on your desktop showing the output
     from an arbitrary terminal program.
 
+:doc:`Clipboard <kittens/clipboard>`
+    Copy/paste to the clipboard from shell scripts, even over SSH.
+
+
 .. _sessions:
 
 Startup Sessions

docs/kittens/clipboard.rst

@@ -0,0 +1,27 @@
+clipboard - copy/paste to the system clipboard
+==================================================
+
+.. highlight:: sh
+
+
+The ``clipboard`` kitten can be used to read or write to the system clipboard
+from the shell. It even works over SSH. Using it is as simple as::
+
+    echo hooray | kitty +kitten clipboard
+
+All text received on :file:`stdin` is copied to the clipboard.
+
+To get text from the clipboard you have to enable reading of the clipboard
+in :opt:`clipboard_control` in :file:`kitty.conf`. Once you do that, you can
+use::
+
+    kitty +kitten clipboard --get-clipboard
+
+
+.. program:: kitty +kitten clipboard
+
+
+Command Line Interface
+--------------------------
+
+.. include:: /generated/cli-kitten-clipboard.rst

kittens/clipboard/main.py

@@ -45,15 +45,19 @@ type=bool-set
 Use the primary selection rather than the clipboard on systems that support it,
 such as X11.
 '''.format
+help_text = '''\
+Read or write to the system clipboard.
+
+To set the clipboard text, pipe in the new text on stdin. Use the
+:option:`--get-clipboard` option to output the current clipboard contents to
+:file:`stdout`. Note that you must enable reading of clipboard in
+:file:`kitty.conf` first.
+'''
+usage = ''
 
 
 def main(args):
-    msg = '''\
-Read or write to the system clipboard.
-
-To set the clipboard text, pipe in the new text on stdin. Use the --get-clipboard option \
-to output the current clipboard contents to stdout. Note that you must enable reading of clipboard in kitty.conf first. '''
-    args, items = parse_args(args[1:], OPTIONS, '', msg, 'clipboard')
+    args, items = parse_args(args[1:], OPTIONS, usage, help_text, 'kitty +kitten clipboard')
     if items:
         raise SystemExit('Unrecognized extra command line arguments')
     data = None
@@ -74,3 +78,7 @@ to output the current clipboard contents to stdout. Note that you must enable re
 
 if __name__ == '__main__':
     main(sys.argv)
+elif __name__ == '__doc__':
+    sys.cli_docs['usage'] = usage
+    sys.cli_docs['options'] = OPTIONS
+    sys.cli_docs['help_text'] = help_text