Add docs for the notify kitten

docs/changelog.rst

@@ -24,6 +24,15 @@ abilities, such as: :opt:`symbol_map`, :opt:`text_composition_strategy`,
 :opt:`font_features` and :opt:`modify_font`. kitty knows text rendering is
 important, and goes the extra mile for it.
 
+Desktop notifications [0.36]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|kitty| now has a :doc:`notify </kittens/notify>` kitten that can be used to
+display desktop notifications from the command line, even over SSH. It has
+support for icons, buttons, waiting, updating notifications, waiting till
+the notification is closed, etc. The underlying :doc:`desktop-notifications`
+protocol has been expanded to support all these features.
+
 Wayland goodies [0.34]
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -70,7 +79,7 @@ Detailed list of changes
 
 - Support `OpenType Variable fonts <https://en.wikipedia.org/wiki/Variable_font>`__ (:iss:`3711`)
 
-- A new ``choose-fonts`` kitten that provides a UI with font previews to ease selection of fonts. Also has support for font features and variable fonts
+- A new :doc:`choose-fonts </kittens/choose-fonts>` kitten that provides a UI with font previews to ease selection of fonts. Also has support for font features and variable fonts
 
 - Allow animating the blinking of the cursor. See :opt:`cursor_blink_interval` for how to configure it
 
@@ -80,6 +89,9 @@ Detailed list of changes
 
 - A new option :opt:`second_transparent_bg` to make a second background color semi-transparent via :opt:`background_opacity`. Useful for things like cursor line highlight in editors (:iss:`7646`)
 
+- A new :doc:`notify </kittens/notify>` kitten to show desktop notifications
+  from the command line with support for icons, buttons and more.
+
 - Desktop notifications protocol: Add support for icons, buttons, closing of notifications, expiry of notifications, updating of notifications and querying if the terminal emulator supports the protocol (:iss:`7657`, :iss:`7658`, :iss:`7659`)
 
 - A new option :opt:`filter_notification` to filter out or perform arbitrary actions on desktop notifications based on sophisticated criteria (:iss:`7670`)

docs/desktop-notifications.rst

@@ -35,6 +35,15 @@ To show a message with a title and a body::
     printf '\x1b]99;i=1:d=0;Hello world\x1b\\'
     printf '\x1b]99;i=1:p=body;This is cool\x1b\\'
 
+.. tip::
+
+   |kitty| also comes with its own :doc:`statically compiled command line tool </kittens/notify>` to easily display
+   notifications, with all their advanced features. For example:
+
+   .. code-block:: sh
+
+        kitten notify "Hello world" A good day to you
+
 The most important key in the metadata is the ``p`` key, it controls how the
 payload is interpreted. A value of ``title`` means the payload is setting the
 title for the notification. A value of ``body`` means it is setting the body,

docs/kittens/notify.rst

@@ -0,0 +1,43 @@
+notify
+==================================================
+
+.. only:: man
+
+    Overview
+    --------------
+
+Show pop-up system notifications.
+
+.. highlight:: sh
+
+.. versionadded:: 0.36.0
+   The notify kitten
+
+The ``notify`` kitten can be used to show pop-up system notifications
+from the shell. It even works over SSH. Using it is as simple as::
+
+    kitten notify "Good morning" Hello world, it is a nice day!
+
+To add an icon, use::
+
+    kitten notify --icon-path /path/to/some/image.png "Good morning" Hello world, it is a nice day!
+    kitten notify --icon firefox "Good morning" Hello world, it is a nice day!
+
+
+To be informed when the notification is activated::
+
+    kitten notify --wait-for-completion "Good morning" Hello world, it is a nice day!
+
+Then, the kitten will wait till the notification is either closed or activated.
+If activated, a ``0`` is printed to :file:`STDOUT`. You can press the
+:kbd:`Esc` or :kbd:`Ctrl+c` keys to abort, closing the notification.
+
+To add buttons to the notification::
+
+    kitten notify --wait-for-completion --button One --button Two "Good morning" Hello world, it is a nice day!
+
+.. program:: kitty +kitten notify
+
+.. tip:: Learn about the underlying :doc:`/desktop-notifications` escape code protocol.
+
+.. include:: /generated/cli-kitten-notify.rst