Add some docs for the ssh kitten

docs/conf.py

@@ -200,6 +200,13 @@ def commit_role(
 def write_cli_docs(all_kitten_names: Iterable[str]) -> None:
     from kitty.cli import option_spec_as_rst
     from kitty.launch import options_spec as launch_options_spec
+    from kittens.ssh.copy import option_text
+    from kittens.ssh.options.definition import copy_message
+    with open('generated/ssh-copy.rst', 'w') as f:
+        f.write(option_spec_as_rst(
+            appname='copy', ospec=option_text, heading_char='^',
+            usage='file-or-dir-to-copy ...', message=copy_message
+        ))
     with open('generated/launch.rst', 'w') as f:
         f.write(option_spec_as_rst(
             appname='launch', ospec=launch_options_spec, heading_char='_',

docs/faq.rst

@@ -46,7 +46,7 @@ terminfo files to the server::
 
     kitty +kitten ssh myserver
 
-This ssh kitten takes all the same command line arguments
+This :doc:`ssh kitten <kittens/ssh>` takes all the same command line arguments
 as ssh, you can alias it to something small in your shell's rc files to avoid
 having to type it each time::
 

docs/kittens/ssh.rst

@@ -0,0 +1,65 @@
+Truly convenient SSH
+=========================================
+
+The ssh kitten allows you to login easily to remote servers, and automatically
+setup the environment there to be as comfortable as your local shell. You
+can specify environment variables to set on the remote server and
+files to copy there, making your remote experience just like your
+local shell. Additionally, it automatically sets up :ref:`shell_integration` on
+the remote server and copies the kitty terminfo database there.
+
+The ssh kitten is a thin wrapper around the traditional `ssh <https://man.openbsd.org/ssh>`__
+command line program and supports all the same options and arguments and configuration.
+In most scenarios it is in fact a drop in replacement for ``ssh``. To try it
+out, simply run:
+
+.. code-block:: sh
+
+    kitty +kitten ssh some-hostname-to-connect-to
+
+You should end up at a shell prompt on the remote server, with shell
+integration enabled. If you like it you can add an alias to it in you shell's
+rc files:
+
+.. code-block:: sh
+
+    alias s=kitty +kitten ssh
+
+So you can now type just ``s hostname`` to connect.
+
+The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf`
+file where you can specify environment variables to set on the remote server
+and files to copy from your local machine to the remote server. Let's see a
+quick example:
+
+.. code-block:: conf
+
+   # Copy the files and directories needed to setup some common tools
+   copy .zshrc .vimrc .vim
+   # Setup some environment variables
+   env SOME_VAR=x
+   # COPIED_VAR will have the same value on the remote server as it does locally
+   env COPIED_VAR=_kitty_copy_env_var_
+
+   # Create some per hostname settings
+   hostname *.myservers.net
+   copy env-files
+   env SOMETHING=else
+
+   hostname somehost.org
+   copy --dest=foo/bar some-file
+   copy --glob some/files.*
+
+
+See below for full details on the syntax and options of :file:`ssh.conf`.
+
+
+.. include:: /generated/conf-kitten-ssh.rst
+
+
+.. _ssh_copy_command:
+
+The copy command
+--------------------
+
+.. include:: /generated/ssh-copy.rst

docs/kittens_intro.rst

@@ -15,6 +15,7 @@ Extend with kittens
    kittens/remote_file
    kittens/hyperlinked_grep
    kittens/transfer
+   kittens/ssh
    kittens/custom
    kittens/*