Cleanup previous PR

docs/conf.py

@@ -717,7 +717,7 @@ def setup_man_pages() -> None:
     base = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
     for x in glob.glob(os.path.join(base, 'docs/kittens/*.rst')):
         kn = os.path.basename(x).rpartition('.')[0]
-        if kn == 'custom':
+        if kn in ('custom', 'developing-builtin-kittens'):
             continue
         cd = get_kitten_cli_docs(kn) or {}
         khn = kn.replace('_', '-')

docs/kittens/cli_interfacing.rst

@@ -1,90 +0,0 @@
-CLI Interfacing
-===============
-
-While developing Kittens for Kitty, interfacing with CLI is handy for passing values and arguments. For this purpose, Kitty has an internal implementation of CLI interfacing with kittens.
-
-*While working with kittens, Kitty relies on internal implementations rather than external, third-party dependencies. The same applies to CLI implementation.*
-
-Procedure to Add CLI into Kittens
----------------------------------
-
-Modify the `gen/go_code.py`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Edit the line ``for kitten in wrapped_kittens() + ('pager',):`` (line 469) and modify it to ``for kitten in wrapped_kittens() + ('pager', '{KITTEN_NAME}',):``.
-
-Create a `__init__.py` File in Your Kittens Folder
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Since Kitty interfaces the CLI through Python, you need to create the ``__init__.py`` file in the kitten's directory you are working with.
-
-Template for `main.go`
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: go
-
-    package {KITTEN_NAME}
-
-    import (
-        "fmt"
-        "kitty/tools/cli"
-    )
-
-    var _ = fmt.Print
-
-    func main(_ *cli.Command, opts_ *Options, args []string) (rc int, err error) {
-        return
-    }
-
-    func EntryPoint(parent *cli.Command) {
-        create_cmd(parent, main)
-    }
-
-Template for `main.py`
-^^^^^^^^^^^^^^^^^^^^^^
-
-The ``main.py`` contains the CLI definition for Kitty. Here, you define the options, arguments, values, and finally the definition and help text.
-
-.. code-block:: python
-
-    #!/usr/bin/env python
-    # License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
-
-    import sys
-
-    OPTIONS = r'''
-    --identifier -i
-    The identifier of this notification. If a notification with the same identifier
-    is already displayed, it is replaced/updated.
-    --wait-till-closed
-    type=bool-set
-    Wait until the notification is closed. If the user activates the notification,
-    "activated" is printed to STDOUT before quitting.
-    '''.format
-
-    help_text = '''\
-    Send notifications to the user that are displayed to them via the
-    desktop environment's notifications service. Works over SSH as well.
-    '''
-
-    usage = 'TITLE [BODY ...]'
-
-    if __name__ == '__main__':
-        raise SystemExit('This should be run as kitten clipboard')
-    elif __name__ == '__doc__':
-        cd = sys.cli_docs  # type: ignore
-        cd['usage'] = usage
-        cd['options'] = OPTIONS
-        cd['help_text'] = help_text
-        cd['short_desc'] = 'Send notifications to the user'
-
-Edit the `tools/cmd/tool/main.go`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Add the entry point of the kitten into ``tools/cmd/tool/main.go``.
-
-First, import the kitten into this file. To do this, add ``"kitty/kittens/{KITTEN_NAME}"`` into the ``import ( ... )``.
-
-Finally, add ``{KITTEN_NAME}.EntryPoint(root)`` into the ``func KittyToolEntryPoints(root *cli.Command)`` and done!
-
-With these five steps, you are ready to interface your kitten with CLI as specified by Kitty.

docs/kittens/custom.rst

@@ -348,6 +348,14 @@ See `the code <https://github.com/kovidgoyal/kitty/tree/master/kittens/diff>`__
 for the builtin :doc:`diff kitten </kittens/diff>` for examples of creating more
 options and keyboard shortcuts.
 
+
+Developing builtin kittens for inclusion with kitty
+----------------------------------------------------------
+
+There is documentation for :doc:`developing-builtin-kittens` which are written in the Go
+language.
+
+
 .. _external_kittens:
 
 Kittens created by kitty users

docs/kittens/developing-builtin-kittens.rst

@@ -0,0 +1,119 @@
+Developing builtin kittens
+=============================
+
+Builtin kittens in kitty are written in the Go language, with small Python
+wrapper scripts to define command line options and handle UI integration.
+
+Getting started
+-----------------------
+
+To get started with creating a builtin kitten, one that will become part of kitty
+and be available as ``kitten my-kitten``, create a directory named
+:file:`my_kitten` in the :file:`kittens` directory. Then, in this directory
+add three, files: :file:`__init__.py` (an empty file), :file:`__main__.py` and
+:file:`main.go`.
+
+Template for `main.py`
+^^^^^^^^^^^^^^^^^^^^^^
+
+The file :file:`main.py` contains the command line option definitions for your kitten. Change the actual options and help text below as needed.
+
+.. code-block:: python
+
+    #!/usr/bin/env python
+    # License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+    import sys
+
+    # See the file kitty/cli.py in the kitty sourcecode for more examples of
+    # the syntax for defining options
+    OPTIONS = r'''
+    --some-string-option -s
+    default=my_default_value
+    Help text for a simple option taking a string value.
+
+
+    --some-boolean-option -b
+    type=bool-set
+    Help text for a boolean option defaulting to false.
+
+
+    --some-inverted-boolean-option
+    type=bool-unset
+    Help text for a boolean option defaulting to true.
+
+
+    --an-integer-option
+    type=int
+    default=13
+    bla bla
+
+
+    --an-enum-option
+    choices=a,b,c,d
+    default=a
+    This option can only take the values a, b, c, or d
+    '''.format
+
+    help_text = '''\
+    The introductory help text for your kitten.
+
+    Can contain multiple paragraphs with :bold:`bold`
+    :green:`colored`, :code:`code`, :link:`links <http://url>` etc.
+    formatting.
+
+    Option help strings can also use this formatting.
+    '''
+
+    # The usage string for your kitten
+    usage = 'TITLE [BODY ...]'
+    short_description = 'some short description of your kitten it will show up when running kitten without arguments to list all kittens`
+
+    if __name__ == '__main__':
+        raise SystemExit('This should be run as kitten my-kitten')
+    elif __name__ == '__doc__':
+        cd = sys.cli_docs  # type: ignore
+        cd['usage'] = usage
+        cd['options'] = OPTIONS
+        cd['help_text'] = help_text
+        cd['short_desc'] = short_description
+
+
+Template for `main.go`
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: go
+
+    package my_kitten
+
+    import (
+        "fmt"
+
+        "kitty/tools/cli"
+    )
+
+    var _ = fmt.Print
+
+    func main(_ *cli.Command, opts *Options, args []string) (rc int, err error) {
+        // Here rc is the exit code for the kitten which should be 1 or higher if err is not nil
+        fmt.Println("Hello world!")
+        fmt.Println(args)
+        fmt.Println(fmt.Sprintf("%#v", opts))
+        return
+    }
+
+    func EntryPoint(parent *cli.Command) {
+        create_cmd(parent, main)
+    }
+
+Edit :file:`tools/cmd/tool/main.go`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Add the entry point of the kitten into :file:`tools/cmd/tool/main.go`.
+
+First, import the kitten into this file. To do this, add :code:`"kitty/kittens/my_kitten"` into the :code:`import ( ... )` section at the top.
+Then, add ``my_kitten.EntryPoint(root)`` into ``func KittyToolEntryPoints(root *cli.Command)`` and you are done. After running make you should
+be able to test your kitten by running::
+
+    kitten my-kitten
+