From b11b04ef67a8b44b5755a8cd22eed03b508d8ceb Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Wed, 17 Nov 2021 10:33:37 +0530
Subject: [PATCH] Start documenting the file transfer kitten

---
 docs/kittens/remote_file.rst |  5 ++++-
 docs/kittens/transfer.rst    | 26 ++++++++++++++++++++++++++
 docs/kittens_intro.rst       |  6 ++++++
 kittens/transfer/main.py     | 19 ++++++++++++++-----
 4 files changed, 50 insertions(+), 6 deletions(-)
 create mode 100644 docs/kittens/transfer.rst

diff --git a/docs/kittens/remote_file.rst b/docs/kittens/remote_file.rst
index d7d3e4b30..bc96f0199 100644
--- a/docs/kittens/remote_file.rst
+++ b/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
diff --git a/docs/kittens/transfer.rst b/docs/kittens/transfer.rst
new file mode 100644
index 000000000..03e74e3d8
--- /dev/null
+++ b/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
diff --git a/docs/kittens_intro.rst b/docs/kittens_intro.rst
index 265c2f715..93847a333 100644
--- a/docs/kittens_intro.rst
+++ b/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,
diff --git a/kittens/transfer/main.py b/kittens/transfer/main.py
index 2154229cf..99e17e476 100644
--- a/kittens/transfer/main.py
+++ b/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
-large files, so use with care.
+partial transfers. Note that this will actually degrade performance on fast links with small
+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',
-        'kitty transfer', result_class=TransferCLIOptions
+        args[1:], option_text, usage, help_text,
+        '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