diff --git a/docs/conf.py b/docs/conf.py index 06faae7ca..3c894aa71 100644 --- a/docs/conf.py +++ b/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('_', '-') diff --git a/docs/kittens/cli_interfacing.rst b/docs/kittens/cli_interfacing.rst deleted file mode 100644 index 9f2ad9769..000000000 --- a/docs/kittens/cli_interfacing.rst +++ /dev/null @@ -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 - - 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. diff --git a/docs/kittens/custom.rst b/docs/kittens/custom.rst index 41b21eeaa..ede83ba3c 100644 --- a/docs/kittens/custom.rst +++ b/docs/kittens/custom.rst @@ -348,6 +348,14 @@ See `the code `__ for the builtin :doc:`diff kitten ` 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 diff --git a/docs/kittens/developing-builtin-kittens.rst b/docs/kittens/developing-builtin-kittens.rst new file mode 100644 index 000000000..e5ba9fa03 --- /dev/null +++ b/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 + + 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 ` 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 +