Add messaging docs for optional features and kernel subshells (#1045)

* Add messaging docs for optional features and kernel subshells

* Use ID rather than id in text

* Review comment

Author: ianthomas23

docs/messaging.rst

@@ -97,7 +97,7 @@ Message Header
 --------------
 
 The message ``header`` contains information about the message,
-such as unique identifiers for the originating session and the actual message id,
+such as unique identifiers for the originating session and the actual message ID,
 the type of message, the version of the Jupyter protocol,
 and the date the message was created.
 In addition, there is a username field, e.g. for the process that generated the
@@ -118,27 +118,34 @@ so that frontends can label the various messages in a meaningful way.
         "msg_type": str,
         # the message protocol version
         "version": "5.0",
+        # Optional subshell_id
+        "subshell_id": str | None,
     }
 
 .. note::
 
-    The ``session`` id in a message header identifies a unique entity with state,
+    The ``session`` ID in a message header identifies a unique entity with state,
     such as a kernel process or client process.
 
-    A client session id, in message headers from a client, should be unique among
+    A client session ID, in message headers from a client, should be unique among
     all clients connected to a kernel. When a client reconnects to a kernel, it
-    should use the same client session id in its message headers. When a client
-    restarts, it should generate a new client session id.
+    should use the same client session ID in its message headers. When a client
+    restarts, it should generate a new client session ID.
 
-    A kernel session id, in message headers from a kernel, should identify a
-    particular kernel process. If a kernel is restarted, the kernel session id
+    A kernel session ID, in message headers from a kernel, should identify a
+    particular kernel process. If a kernel is restarted, the kernel session ID
     should be regenerated.
 
-    The session id in a message header can be used to identify the sending entity.
+    The session ID in a message header can be used to identify the sending entity.
     For example, if a client disconnects and reconnects to a kernel, and messages
-    from the kernel have a different kernel session id than prior to the disconnect,
+    from the kernel have a different kernel session ID than prior to the disconnect,
     the client should assume that the kernel was restarted.
 
+    The ``subshell_id`` is only used in shell messages of kernels that support
+    subshells (:ref:`kernel_subshells`). If it is not included or is ``None`` then the
+    shell message is handled by the parent subshell (main shell), if it is a string
+    subshell ID then it is handled by the subshell with that ID.
+
 .. versionchanged:: 5.0
 
     ``version`` key added to the header.
@@ -150,6 +157,10 @@ so that frontends can label the various messages in a meaningful way.
     so implementers are strongly encouraged to include it.
     It will be mandatory in 5.1.
 
+.. versionchanged:: 5.5
+
+    ``subshell_id`` added to the header.
+
 Parent header
 -------------
 
@@ -913,7 +924,7 @@ Message type: ``comm_info_reply``::
         # 'ok' if the request succeeded or 'error', with error information as in all other replies.
         'status' : 'ok',
 
-        # A dictionary of the comms, indexed by uuids.
+        # A dictionary of the comms, indexed by UUIDs.
         'comms': {
             comm_id: {
                 'target_name': str,
@@ -997,14 +1008,20 @@ Message type: ``kernel_info_reply``::
         'banner': str,
 
         # A boolean flag which tells if the kernel supports debugging in the notebook.
-        # Default is False
+        # Default is False.
+        # Deprecated as replaced by 'supported_features'=['debugger'] (see below).
         'debugger': bool,
 
         # Optional: A list of dictionaries, each with keys 'text' and 'url'.
         # These will be displayed in the help menu in the notebook UI.
         'help_links': [
             {'text': str, 'url': str}
         ],
+
+        # Optional: A list of optional features such as 'debugger' and
+        # 'kernel subshells'. Introduced by Jupyter Enhancement Proposal 92
+        # https://github.com/jupyter/enhancement-proposals/pull/92
+        'supported_features': [str]
     }
 
 Refer to the lists of available `Pygments lexers <http://pygments.org/docs/lexers/>`_
@@ -1031,6 +1048,10 @@ and `codemirror modes <http://codemirror.net/mode/index.html>`_ for those fields
 
     ``language`` moved to ``language_info.name``
 
+.. versionchanged:: 5.5
+
+    ``supported_features`` added and ``debugger`` deprecated.
+
 Messages on the Control (ROUTER/DEALER) channel
 ===============================================
 
@@ -1313,6 +1334,86 @@ of the debugger to the ``global`` scope to inspect it after debug session.
 
 .. versionadded:: 5.5
 
+.. _kernel_subshells:
+
+Kernel subshells
+----------------
+
+Kernel subshells are separate threads of execution within the same kernel process that
+were introduced by
+`Jupyter Enhancement Proposal 91 <https://github.com/jupyter/enhancement-proposals/pull/91>`_.
+Kernels supporting subshells must include ``'kernel subshells'`` in ``'supported_features'``
+in :ref:`kernel info <msging_kernel_info>` reply messages.
+
+Create subshell
+~~~~~~~~~~~~~~~
+
+In a kernel that supports subshells, this creates a new subshell (running in a separate thread)
+and returns its unique ID. In a kernel that does not support subshells an error is logged and
+no reply is sent.
+
+Message type: ``create_subshell_request``::
+
+    content = {
+    }
+
+Message type: ``create_subshell_reply``::
+
+    content = {
+        # 'ok' if the request succeeded or 'error', with error information as in all other replies.
+        'status' : 'ok',
+
+        # The ID of the subshell, unique within the kernel.
+        'subshell_id': str,
+    }
+
+.. versionadded:: 5.5
+
+Delete subshell
+~~~~~~~~~~~~~~~
+
+In a kernel that supports subshells, this deletes a subshell identified by its unique ID.
+In a kernel that does not support subshells an error is logged and no reply is sent.
+
+Message type: ``delete_subshell_request``::
+
+    content = {
+        # The ID of the subshell.
+        'subshell_id': str
+    }
+
+Message type: ``delete_subshell_reply``::
+
+    content = {
+        # 'ok' if the request succeeded or 'error', with error information as in all other replies.
+        'status': 'ok',
+    }
+
+.. versionadded:: 5.5
+
+List subshell
+~~~~~~~~~~~~~
+
+In a kernel that supports subshells, this returns a list of the IDs of all subshells that exist
+in that kernel. In a kernel that does not support subshells an error is logged and no reply is sent.
+
+Message type: ``list_subshell_request``::
+
+    content = {
+    }
+
+Message type: ``list_subshell_reply``::
+
+    content = {
+        # 'ok' if the request succeeded or 'error', with error information as in all other replies.
+        'status': 'ok',
+
+        # A list of subshell IDs.
+        'subshell_id': [str]
+    }
+
+.. versionadded:: 5.5
+
 Messages on the IOPub (PUB/SUB) channel
 =======================================
 
@@ -1755,6 +1856,10 @@ Changelog
 
 - Added ``debug_request/reply`` messages
 - Added ``debug_event`` message
+- Added ``supported_features`` in :ref:`kernel info <msging_kernel_info>` reply messages.
+- Deprecated ``debugger`` in :ref:`kernel info <msging_kernel_info>` reply messages as
+  replaced with ``supported_features``.
+- Added ``create_subshell``, ``delete_subshell`` and ``list_subshell`` messages.
 
 5.4
 ---