Document the new quick-access-terminal kitten

docs/changelog.rst

@@ -97,7 +97,7 @@ Detailed list of changes
 0.42.0 [future]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- The :doc:`panel kitten </kittens/panel>` can now be used to :ref:`quake`
+- A new :doc:`kitten quick-access-terminal </kittens/quick-access-terminal>` can now be used to :ref:`quake`
 
 - The :doc:`panel kitten </kittens/panel>` now works on macOS as well as Wayland (:iss:`2590`)
 

docs/conf.py

@@ -12,7 +12,6 @@ import os
 import re
 import subprocess
 import sys
-import textwrap
 import time
 from functools import lru_cache, partial
 from typing import Any, Callable, Dict, Iterable, Iterator, List, Tuple
@@ -31,7 +30,6 @@ if kitty_src not in sys.path:
 from kitty.conf.types import Definition, expand_opt_references  # noqa
 from kitty.constants import str_version, website_url # noqa
 from kitty.fast_data_types import Shlex, TEXT_SIZE_CODE  # noqa
-from kittens.panel.main import default_quake_cmdline  # noqa
 
 # config {{{
 # -- Project information -----------------------------------------------------
@@ -122,9 +120,6 @@ string_replacements = {
     '_kitty_install_cmd': 'curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin',
     '_build_go_version': go_version('../go.mod'),
     '_text_size_code': str(TEXT_SIZE_CODE),
-    '_default_quake_cmdline': textwrap.fill(
-        default_quake_cmdline, break_on_hyphens=False, break_long_words=False, initial_indent=' ' * 4, subsequent_indent=' ' * 8, width=77,
-    ).replace('\n', ' \\\n'),
 }
 
 

docs/kittens/panel.rst

@@ -14,8 +14,7 @@ screen or as the desktop wallpaper, that shows the output from an arbitrary
 terminal program.
 
 It is useful for showing status information or notifications on your desktop
-using terminal programs instead of GUI toolkits. It can also be used for a
-:ref:`Quake like quick access terminal <quake>`.
+using terminal programs instead of GUI toolkits.
 
 .. figure:: ../screenshots/panel.png
    :alt: Screenshot, showing a sample panel
@@ -44,7 +43,7 @@ activity, CPU load, date/time, etc.
 
 Using this kitten is simple, for example::
 
-    kitty +kitten panel sh -c 'printf "\n\n\nHello, world."; sleep 5s'
+    kitten panel sh -c 'printf "\n\n\nHello, world."; sleep 5s'
 
 This will show ``Hello, world.`` at the top edge of your screen for five
 seconds. Here, the terminal program we are running is :program:`sh` with a script
@@ -53,7 +52,7 @@ you like, as demonstrated in the screenshot above.
 
 If you are on Wayland or macOS, you can, for instance run::
 
-    kitty +kitten panel --edge=background htop
+    kitten panel --edge=background htop
 
 to display ``htop`` as your desktop background. Remember this works in everything
 but GNOME and also, in sway, you have to disable the background wallpaper as
@@ -79,10 +78,10 @@ disappears at a key press. To do so use the following command:
 
 .. code-block:: sh
 
-_default_quake_cmdline
+    kitten quick-access-terminal
 
-Run this command in a terminal, and a quick access kitty panel will show up at
-the top of your screen. Run it again, and the panel will be hidden.
+Run this command in a terminal, and a quick access kitty window will show up at
+the top of your screen. Run it again, and the window will be hidden.
 
 Simply bind this command to some key press in your window manager or desktop
 environment settings and then you have a quick access terminal at a single key press.
@@ -91,11 +90,6 @@ position of the quick access panel. In particular, the :option:`kitty +kitten pa
 :option:`kitty +kitten panel --override` options can be used to theme the terminal appropriately,
 making it look different from regular kitty terminal instances.
 
-.. note::
-   If you want to start the quake terminal hidden, use
-   :option:`kitty +kitten panel --start-as-hidden`, useful if you are starting it in the background
-   during computer startup.
-
 
 Controlling panels via remote control
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -103,7 +97,7 @@ Controlling panels via remote control
 You can control panels via the kitty :doc:`remote control </remote-control>` facility. Create a panel
 with remote control enabled::
 
-    kitty +kitten panel -o allow_remote_control=socket-only --lines=2 \
+    kitten panel -o allow_remote_control=socket-only --lines=2 \
         --listen-on=unix:/tmp/panel kitten run-shell
 
 

docs/kittens/quick-access-terminal.rst

@@ -0,0 +1,69 @@
+.. _quake:
+
+Make a Quake like quick access terminal
+====================================================================================================
+
+.. highlight:: sh
+
+.. only:: man
+
+    Overview
+    --------------
+
+.. versionadded:: 0.42.0
+   Works on macOS and Wayland, except for GNOME.
+
+
+This kitten can be used to make a quick access terminal, that appears and
+disappears at a key press. To do so use the following command:
+
+.. code-block:: sh
+
+    kitten quick-access-terminal
+
+Run this command in a terminal, and a quick access kitty window will show up at
+the top of your screen. Run it again, and the window will be hidden.
+
+To make the terminal appear and disappear at a key press:
+
+.. tab:: Linux
+
+   Simply bind the above command to some key press in your window manager or desktop
+   environment settings and then you have a quick access terminal at a single key press.
+
+.. tab:: macOS
+
+   In kitty, run the above command to show the quick access window, then close
+   it by running the command again or pressing :kbd:`ctrl+d`. Now go to :guilabel:`System
+   Preferences->Keyboard->Keyboard Shortcuts->Services->General` and set a shortcut for
+   the :guilabel:`Quick access to kitty` entry.
+
+.. note::
+
+   This kitten uses the :doc:`panel kitten </kittens/panel>` under the
+   hood.
+
+Configuration
+------------------------
+
+You can configure the appearance and behavior of the quick access window
+by creating a :file:`quick-access-terminal.conf` file in your
+:ref:`kitty config folder <confloc>`. In particular, you can use the
+:opt:`kitty_conf <kitten-quick_access_terminal.kitty_conf>` option to change
+various kitty settings, just for the quick access window.
+
+See below for the supported configuration directives:
+
+
+.. include:: /generated/conf-kitten-quick_access_terminal.rst
+
+
+.. include:: /generated/cli-kitten-quick_access_terminal.rst
+
+
+Sample quick-access-terminal.conf
+---------------------------------------
+
+You can download a sample :file:`quick-access-terminal.conf` file with all default settings and
+comments describing each setting by clicking: :download:`sample quick-access-terminal.conf
+</generated/conf/quick_access_terminal.conf>`.

kittens/panel/main.py

@@ -34,14 +34,6 @@ from kitty.types import LayerShellConfig
 from kitty.typing_compat import BossType, EdgeLiteral
 from kitty.utils import log_error
 
-quake = (
-    'kitty +kitten panel --edge=top --layer=overlay --lines=25 --focus-policy=exclusive'
-    ' -o background_opacity=0.8 --toggle-visibility --single-instance --instance-group=quake'
-)
-default_quake_cmdline = f'{quake} --exclusive-zone=0 --override-exclusive-zone --detach'
-default_macos_quake_cmdline = f'{quake}'
-
-
 args = PanelCLIOptions()
 help_text = 'Use a command line program to draw a GPU accelerated panel on your desktop'
 usage = '[cmdline-to-run ...]'

kitty/main.py

@@ -63,7 +63,6 @@ from .utils import (
     log_error,
     parse_os_window_state,
     safe_mtime,
-    shlex_split,
     startup_notification_handler,
 )
 
@@ -533,14 +532,13 @@ def main(called_from_panel: bool = False) -> None:
     global redirected_for_quick_access
     try:
         if is_macos and launched_by_launch_services and not called_from_panel:
+            if is_quick_access_terminal_app:
+                # we were started by launch services, use the kitten to read
+                # the config and re-run
+                os.execl(kitten_exe(), kitten_exe(), 'quick-access-terminal')
             with suppress(OSError):
                 os.chdir(os.path.expanduser('~'))
             set_use_os_log(True)
-            if is_quick_access_terminal_app:
-                from kittens.panel.main import default_macos_quake_cmdline
-                from kittens.panel.main import main as panel_main
-                panel_main(list(shlex_split(default_macos_quake_cmdline))[2:])
-                return
         kitty_main(called_from_panel)
     except Exception:
         import traceback