Document the new run-shell kitten

Author: kovidgoyal

docs/changelog.rst

@@ -40,6 +40,8 @@ Detailed list of changes
 
 - A new escape code ``<ESC>[22J`` that moves the current contents of the screen into the scrollback before clearing it
 
+- A new kitten :ref:`run-shell <run_shell>` to allow creating sub-shells with shell integration enabled
+
 - A new option :opt:`text_fg_override_threshold` to force text colors to have high contrast regardless of color scheme (:pull:`6283`)
 
 - When resizing OS Windows make the animation less jerky. Also show the window size in cells during the resize (:iss:`6341`)

docs/shell-integration.rst

@@ -292,15 +292,39 @@ In order to avoid remote code execution, kitty will only execute the configured
 editor and pass the file path to edit to it.
 
 
+.. _run_shell:
+
+Using shell integration in sub-shells, containers, etc.
+-----------------------------------------------------------
+
+To start a sub-shell with shell integration automatically setup, simply run::
+
+    kitten run-shell
+
+This will start a sub-shell using the same binary as the currently running
+shell, with shell-integration enabled. To start a particular shell use::
+
+    kitten run-shell --shell=/bin/bash
+
+To run a command before starting the shell use::
+
+    kitten run-shell ls .
+
+This will run ``ls .`` before starting the shell.
+
+This will even work on remote systems where kitty itself is not installed,
+provided you use the :doc:`SSH kitten <kittens/ssh>` to connect to the system.
+Use ``kitten run-shell --help`` to learn more.
+
 .. _manual_shell_integration:
 
 Manual shell integration
 ----------------------------
 
 The automatic shell integration is designed to be minimally intrusive, as such
 it won't work for sub-shells, terminal multiplexers, containers, etc.
-For such systems, you should setup manual shell integration by adding some code
-to your shells startup files to load the shell integration script.
+For such systems, you should either use the :ref:`run-shell <run_shell>` command described above or
+setup manual shell integration by adding some code to your shells startup files to load the shell integration script.
 
 First, in :file:`kitty.conf` set:
 

tools/cmd/run_shell/main.go

@@ -44,12 +44,12 @@ func EntryPoint(root *cli.Command) *cli.Command {
 	})
 	sc.Add(cli.OptionSpec{
 		Name: "--shell-integration",
-		Help: "Specify a value for the shell_integration option, overriding the one from kitty.conf.",
+		Help: "Specify a value for the :opt:`shell_integration` option, overriding the one from :file:`kitty.conf`.",
 	})
 	sc.Add(cli.OptionSpec{
 		Name:    "--shell",
 		Default: ".",
-		Help:    "Specify the shell command to run. The default value of :code:`.` will use the parent shell if recognized, falling back to the value of the :code:`shell` option from kitty.conf.",
+		Help:    "Specify the shell command to run. The default value of :code:`.` will use the parent shell if recognized, falling back to the value of the :opt:`shell` option from :file:`kitty.conf`.",
 	})
 	return sc
 }