Document the kitty remote control protocol

Fixes #1646

docs/changelog.rst

@@ -10,6 +10,8 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 - Fix an out of bounds read causing a crash when selecting text with the mouse
   in the alternate screen mode (:iss:`1578`)
 
+- Document the kitty remote control protocol (:iss:`1646`)
+
 
 0.14.2 [2019-06-09]
 ---------------------

docs/conf.py

@@ -276,6 +276,48 @@ def write_cli_docs(all_kitten_names):
 # }}}
 
 
+def write_remote_control_protocol_docs():  # {{{
+    from kitty.cmds import cmap
+    field_pat = re.compile(r'\s*([a-zA-Z0-9_+]+)\s*:\s*(.+)')
+
+    def format_cmd(p, name, cmd):
+        p(name)
+        p('-' * 80)
+        lines = cmd.__doc__.strip().splitlines()
+        fields = []
+        for line in lines:
+            m = field_pat.match(line)
+            if m is None:
+                p(line)
+            else:
+                fields.append((m.group(1), m.group(2)))
+        if fields:
+            p('\nFields are:\n')
+            for (name, desc) in fields:
+                if '+' in name:
+                    title = name.replace('+', ' (required)')
+                else:
+                    title = name
+                    defval = cmd.get_default(name.replace('-', '_'), cmd)
+                    if defval is not cmd:
+                        title = f'{title} (default: {defval})'
+                    else:
+                        title = f'{title} (optional)'
+                p(f':code:`{title}`')
+                p(' ', desc), p()
+        p(), p()
+
+    with open(f'generated/rc.rst', 'w') as f:
+        p = partial(print, file=f)
+        for name in sorted(cmap):
+            cmd = cmap[name]
+            if not cmd.__doc__:
+                continue
+            name = name.replace('_', '-')
+            format_cmd(p, name, cmd)
+# }}}
+
+
 # config file docs {{{
 
 class ConfLexer(RegexLexer):
@@ -537,6 +579,7 @@ def setup(app):
     from kittens.runner import all_kitten_names
     all_kitten_names = all_kitten_names()
     write_cli_docs(all_kitten_names)
+    write_remote_control_protocol_docs()
     write_conf_docs(app, all_kitten_names)
     app.add_lexer('session', SessionLexer())
     app.add_role('link', link_role)

docs/index.rst

@@ -486,3 +486,4 @@ See :doc:`changelog`.
 
     *
     kittens/*
+    generated/rc

docs/rc_protocol.rst

@@ -0,0 +1,29 @@
+Documentation for the kitty remote control protocol
+======================================================
+
+The kitty remote control protocol is a simple protocol that involves sending
+data to kitty in the form of JSON. Any individual command ot kitty has the
+form::
+
+    <ESC>P@kitty-cmd<JSON object><ESC>\
+
+Where ``<ESC>`` is the byte ``0x1b``. The JSON object has the form::
+
+    {
+        'cmd': "command name",
+        'version': "kitty version",
+        'no_response': Optional Boolean,
+        'payload': <Optional JSON object>,
+    }
+
+The ``version`` above is a string of the form :code:`0.14.2`. If you are developing a
+standalone client, use the kitty version that you are developing against. Using
+a version greater than the version of the kitty instance you are talking to,
+will cause a failure.
+
+Set ``no_response`` to True if you dont want a response from kitty.
+
+The optional payload is a JSON object that is specific to the actual command being sent.
+The fields in the object for every command are documented below.
+
+.. include:: generated/rc.rst

docs/remote-control.rst

@@ -134,5 +134,10 @@ still write to the pipes of any other program on the same computer and
 therefore can control |kitty|. It can, however, be useful to block programs
 running on other computers (for example, over ssh) or as other users.
 
+Documentation for the remote control protocol
+-----------------------------------------------
+
+If you wish to develop your own client to talk to |kitty|, you
+can use the :doc:`rc_protocol`.
 
 .. include:: generated/cli-kitty-at.rst