Document the new shell integration features

docs/changelog.rst

@@ -117,6 +117,11 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 0.22.0 [2021-07-26]
 ----------------------
 
+- Integrate kitty closely with common shells such as zsh, fish and bash.
+  This allows lots of niceties such as jumping to previous prompts, opening the
+  output of the last command in a new window, etc. See :ref:`shell_integration`
+  for details.
+
 - Add a new :ref:`action-toggle_layout` action to easily zoom/unzoom a window
 
 - When right clicking to extend a selection, move the nearest selection

docs/glossary.rst

@@ -148,3 +148,8 @@ Variables that kitty sets when running child programs
 
    Set with the values of some common kitty options when running
    kittens, so kittens can use them without needing to load kitty.conf.
+
+
+.. envvar:: KITTY_SHELL_INTEGRATION
+
+   Set when enabling :ref:`shell_integration`.

docs/index.rst

@@ -37,7 +37,8 @@ kitty
 .. tab:: Composable
 
    * Programmble tabs, :ref:`splits <splits_layout>` and multiple :doc:`layouts <layouts>` to manage windows
-   * Browse the :ref:`entire history <scrollback>` or the output from the last command comfortably in pagers and editors
+   * Browse the :ref:`entire history <scrollback>` or the :sc:`output from the last command <show_last_command_output>`
+     comfortably in pagers and editors
    * Edit or download :doc:`remote files <kittens/remote_file>` in an existing SSH session
 
 .. tab:: Cross-platform

docs/shell-integration.rst

@@ -8,3 +8,131 @@ kitty has the ability to integrate closely within common shells, such as `zsh
 <https://www.gnu.org/software/bash/>`_ to enable features such as jumping to
 previous prompts in the scrollback, viewing the output of the last command in
 :program:`less`, using the mouse to move the cursor while editing prompts, etc.
+
+Features
+-------------
+
+* Open the output of the last command in a pager such as :program:`less`
+  (:sc:`show_last_command_output`)
+
+* Jump to the previous/next prompt in the scrollback
+  (:sc:`scroll_to_previous_prompt` /  :sc:`scroll_to_next_prompt`)
+
+* Click with the mouse anywhere in the current command to move the cursor there
+
+* The current working directory or the command being executed are automatically
+  displayed in the kitty window titlebar/tab title.
+
+* The text cursor is changed to a bar when editing commands at the shell prompt
+
+* Glitch free window resizing even with complex prompts. Achieved by erasing
+  the prompt on resize and allowing the shell to redraw it cleanly.
+
+* Sophisticated completion for the :program:`kitty` command in the shell
+
+
+Configuration
+---------------
+
+Shell integration is controlled by :opt:`shell_integration`. By default, all
+shell integration is enabled. Individual features can be turned off or it can
+be disabled entirely as well. The :opt:`shell_integration` option takes a space
+separated list of keywords:
+
+disabled
+    turn off all shell integration
+
+no-rc
+    dont modify the shell's rc files to enable integration. Useful if you prefer
+    to :ref:`manually enable integration <manual_shell_integration>`.
+
+no-cursor
+    turn off changing of the text cursor to a bar when editing text
+
+no-title
+    turn off setting the kitty window/tab title based on shell state
+
+no-prompt-mark
+    turn off marking of prompts. This disables jumping to prompt, browsing
+    output of last command and click to move cursor functionality.
+
+no-complete
+    turn off completion for the kitty command.
+
+
+How it works
+-----------------
+
+At startup kitty detects if the shell you have configured (either system wide
+or in kitty.conf) is a supported shell. If so, kitty adds a couple of lines to
+the bottom of the shell's rc files (in an atomic manner) to load the shell
+integration code.
+
+Then, when launching the shell, kitty sets the environment variable
+:envvar:`KITTY_SHELL_INTEGRATION` to the value of the :opt:`shell_integration`
+option. The shell integration code reads the environment variable, turns on the
+specified integration functionality and then unsets the variable so as to not
+pollute the system. This has the nice effect that the changes to the shell's rc
+files become no-ops when running the shell in anything other than kitty itself.
+
+The actual shell integration code uses hooks provided by each shell to send
+special escape codes to kitty, to perform the various tasks. You can see the
+code used for each shell below:
+
+.. raw:: html
+
+    <details>
+    <summary style="cursor: pointer">Click to toggle shell integration code</summary>
+
+.. tab:: zsh
+
+    .. literalinclude:: ../shell-integration/kitty.zsh
+        :language: zsh
+
+
+.. tab:: fish
+
+    .. literalinclude:: ../shell-integration/kitty.fish
+        :language: fish
+
+.. tab:: bash
+
+    .. literalinclude:: ../shell-integration/kitty.bash
+        :language: bash
+
+.. raw:: html
+
+   </details>
+
+
+.. _manual_shell_integration:
+
+Manual shell integration
+----------------------------
+
+If you do not want to rely on kitty's automatic shell integration or if you
+want to setup shell integration for a remote system over SSH, in
+:file:`kitty.conf` set:
+
+.. code-block:: conf
+
+    shell_integration disabled
+
+Then in your shell's rc file, add the lines:
+
+.. code-block:: sh
+
+   export KITTY_SHELL_INTEGRATION="enabled"
+   source /path/to/integration/script
+
+You can get the path to the directory containing the various shell integration
+scripts by looking at the directory displayed by:
+
+.. code-block:: sh
+
+    kitty +runpy "from kitty.constants import *; print(shell_integration_dir)"
+
+The value of :envvar:`KITTY_SHELL_INTEGRATION` is the same as that for
+:opt:`shell_integration`, except if you want to disable shell integration
+completely, in which case simply do not set the
+:envvar:`KITTY_SHELL_INTEGRATION` variable at all.