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/*
 

kittens/ssh/main.py

@@ -357,3 +357,6 @@ if __name__ == '__main__':
     main(sys.argv)
 elif __name__ == '__completer__':
     setattr(sys, 'kitten_completer', complete)
+elif __name__ == '__conf__':
+    from .options.definition import definition
+    sys.options_definition = definition  # type: ignore

kittens/ssh/options/definition.py

@@ -7,6 +7,12 @@
 from kitty.conf.types import Definition
 
 
+copy_message = '''\
+Copy files and directories from the local computer to the remote one. The
+specified files are assumed to be relative to the HOME directory and copied
+to the HOME on the server. Directories are copied recursively. If absolute paths
+are used, they are copied as is.'''
+
 definition = Definition(
     'kittens.ssh',
 )
@@ -26,7 +32,26 @@ against is the hostname used by the remote computer, not the name you pass
 to SSH to connect to it.
 ''')
 
-opt('+copy', '', option_type='copy', add_to_default=False, long_text='''
+opt('+copy', '', option_type='copy', add_to_default=False, long_text=f'''
+{copy_message} For example::
+
+    copy .vimrc .zshrc .config/some-dir
+
+If a file should be copied to some other destination on the remote machine,
+use :code:`--dest`::
+
+    copy --dest some-other-name some-file
+
+Glob patterns can be specified to copy multiple files, with :code:`--glob`::
+
+    copy --glob images/*.png
+
+Files can be excluded when copying with :code:`--exclude`::
+
+    copy --glob --exclude *.jpg --exclude *.bmp images/*
+
+Files whose remote name matches the exclude pattern will not be copied.
+For more details, see :ref:`ssh_copy_command`.
 ''')
 
 opt('+env', '', option_type='env', add_to_default=False, long_text='''

kitty/conf/types.py

@@ -52,6 +52,7 @@ def ref_map() -> Dict[str, str]:
         'watchers': f'{website_url("launch")}#watchers',
         'sessions': f'{website_url("overview")}#startup-sessions',
         'functional': f'{website_url("keyboard-protocol")}#functional-key-definitions',
+        'ssh_copy_command': f'{website_url("kittens/ssh")}#ssh-copy-command',
         'shell_integration': website_url("shell-integration"),
         'github_discussions': 'https://github.com/kovidgoyal/kitty/discussions',
     }