Start documenting the file transfer kitten

docs/kittens/remote_file.rst

@@ -22,12 +22,15 @@ transferred to the remote computer. Note that this happens without needing
 to install *any* special software on the server, beyond ``ls`` that supports
 hyperlinks.
 
+.. seealso:: See the :doc:`transfer` kitten
+
 .. versionadded:: 0.19.0
 
 .. note::
    Nested SSH sessions are not supported. The kitten will always try to copy
    remote files from the first SSH host. This is because there is no way for
-   |kitty| to detect and follow a nested SSH session robustly.
+   |kitty| to detect and follow a nested SSH session robustly. Use the
+   :doc:`transfer` kitten for such situations.
 
 .. note::
    If you have not setup automatic password-less SSH access, then, when

docs/kittens/transfer.rst

@@ -0,0 +1,26 @@
+Transfer files
+================
+
+.. warning::
+   This kitten is currently experimental, use with care.
+
+Transfer files to and from remote computers over the ``TTY`` device itself.
+This means that file transfer works over nested SSH sessions, serial links,
+etc. Anywhere you have a terminal device, you can transfer files.
+
+This kitten support transferring entire directory trees, preserving soft and
+hard links, file permissions and times, etc. It even supports the `rsync
+<https://en.wikipedia.org/wiki/Rsync>`_ protocol to transfer only changes to
+large files and to automatically resume interrupted transfers.
+
+.. seealso:: See the :doc:`remote_file` kitten
+
+.. note::
+   This kitten (which practically means kitty) must be installed on the remote
+   machine. If that is not possible you can use the :doc:`remote_file` kitten
+   instead. Or write your own script to use the underlying file transfer
+   protocol.
+
+.. versionadded:: 0.24.0
+
+.. include:: ../generated/cli-kitten-transfer.rst

docs/kittens_intro.rst

@@ -14,6 +14,7 @@ Extend with kittens
    kittens/hints
    kittens/remote_file
    kittens/hyperlinked_grep
+   kittens/transfer
    kittens/custom
    kittens/*
 
@@ -45,6 +46,11 @@ Some prominent kittens:
     the filename.
 
 
+:doc:`Transfer files <kittens/transfer>`
+    Transfer files and directories seamlessly and easily from remote machines over your existing
+    SSH sessions with a simple command.
+
+
 :doc:`Hyperlinked grep <kittens/hyperlinked_grep>`
     Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`_
     and open the results directly in your favorite editor in the terminal,

kittens/transfer/main.py

@@ -13,6 +13,10 @@ from .receive import receive_main
 from .send import send_main
 
 
+usage = 'source_files_or_directories destination_path'
+help_text = 'Transfer files over the TTY device'
+
+
 def option_text() -> str:
     return '''\
 --direction -d
@@ -23,7 +27,7 @@ Whether to send or receive files.
 
 --mode -m
 default=normal
-choices=mirror
+choices=normal,mirror
 How to interpret command line arguments. In :code:`mirror` mode all arguments
 are assumed to be files on the sending computer and they are mirrored onto the
 receiving computer. In :code:`normal` mode the last argument is assumed to be a
@@ -49,15 +53,15 @@ and ask for confirmation.
 type=bool-set
 If a file on the receiving side already exists, use the rsync algorithm to update it to match
 the file on the sending side, potentially saving lots of bandwidth and also automatically resuming
-partial transfers. Note that this will actually degrade performance on fast links with not too
+partial transfers. Note that this will actually degrade performance on fast links with small
-large files, so use with care.
+files, so use with care.
 '''
 
 
 def parse_transfer_args(args: List[str]) -> Tuple[TransferCLIOptions, List[str]]:
     return parse_args(
-        args[1:], option_text, '', 'Transfer files over the TTY device',
+        args[1:], option_text, usage, help_text,
-        'kitty transfer', result_class=TransferCLIOptions
+        'kitty +kitten transfer', result_class=TransferCLIOptions
     )
 
 
@@ -92,3 +96,8 @@ def main(args: List[str]) -> None:
 
 if __name__ == '__main__':
     main(sys.argv)
+elif __name__ == '__doc__':
+    cd = sys.cli_docs  # type: ignore
+    cd['usage'] = usage
+    cd['options'] = option_text
+    cd['help_text'] = help_text