Update docs about kernelspecs and kernel_info_reply

takluyver · takluyver · commit b4a3f46c790a · 2014-10-24T16:53:10.000-07:00
diff --git a/docs/source/development/kernels.rst b/docs/source/development/kernels.rst
@@ -112,34 +112,16 @@ JSON serialised dictionary containing the following keys and values:
 - **display_name**: The kernel's name as it should be displayed in the UI.
   Unlike the kernel name used in the API, this can contain arbitrary unicode
   characters.
-- **language**: The programming language which this kernel runs. This will be 
-  stored in notebook metadata. This may be used by syntax highlighters to guess
-  how to parse code in a notebook, and frontends may eventually use it to
-  identify alternative kernels that can run some code.
-- **codemirror_mode** (optional): The `codemirror mode <http://codemirror.net/mode/index.html>`_
-  to use for code in this language. This can be a string or a dictionary, as
-  passed to codemirror config. This only needs to be specified if it does not
-  match the value in *language*.
-- **pygments_lexer** (optional): The name of a `Pygments lexer <http://pygments.org/docs/lexers/>`_
-  to use for code in this language, as a string. This only needs to be specified
-  if it does not match the value in *language*.
 - **env** (optional): A dictionary of environment variables to set for the kernel.
   These will be added to the current environment variables before the kernel is
   started.
-- **help_links** (optional): A list of dictionaries, each with keys 'text' and
-  'url'. These will be displayed in the help menu in the notebook UI.
 
 For example, the kernel.json file for IPython looks like this::
 
     {
      "argv": ["python3", "-c", "from IPython.kernel.zmq.kernelapp import main; main()", 
-              "-f", "{connection_file}"], 
-     "codemirror_mode": {
-      "version": 3, 
-      "name": "ipython"
-     }, 
+              "-f", "{connection_file}"],
      "display_name": "IPython (Python 3)", 
-     "language": "python"
     }
 
 To see the available kernel specs, run::
diff --git a/docs/source/development/messaging.rst b/docs/source/development/messaging.rst
@@ -685,11 +685,33 @@ Message type: ``kernel_info_reply``::
         # included in IPython.
         'language_version': 'X.Y.Z',
 
+        # Information about the language of code for the kernel
+        'language_info': {
+            'mimetype': str,
+
+            # Pygments lexer, for highlighting
+            # Only needed if it differs from the top level 'language' field.
+            'pygments_lexer': str,
+
+            # Codemirror mode, for for highlighting in the notebook.
+            # Only needed if it differs from the top level 'language' field.
+            'codemirror_mode': str or dict,
+        },
+
         # A banner of information about the kernel,
         # which may be desplayed in console environments.
         'banner' : str,
+
+        # 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}
+        ],
     }
 
+Refer to the lists of available `Pygments lexers <http://pygments.org/docs/lexers/>`_
+and `codemirror modes <http://codemirror.net/mode/index.html>`_ for those fields.
+
 .. versionchanged:: 5.0
 
     Versions changed from lists of integers to strings.
@@ -700,7 +722,8 @@ Message type: ``kernel_info_reply``::
 
 .. versionchanged:: 5.0
 
-    ``implementation``, ``implementation_version``, and ``banner`` keys are added.
+    ``language_info``, ``implementation``, ``implementation_version``, ``banner``
+    and ``help_links`` keys are added.
 
 .. _msging_shutdown:
 
diff --git a/docs/source/development/wrapperkernels.rst b/docs/source/development/wrapperkernels.rst
@@ -34,6 +34,16 @@ following methods and attributes:
      interprets (e.g. Python). The 'banner' is displayed to the user in console
      UIs before the first prompt. All of these values are strings.
 
+   .. attribute:: language_info
+
+     Language information for :ref:`msging_kernel_info` replies, in a dictionary.
+     This should contain the key ``mimetype`` with the mimetype of code in the
+     target language (e.g. ``'text/x-python'``). It may also contain keys
+     ``codemirror_mode`` and ``pygments_lexer`` if they need to differ from
+     :attr:`language`.
+
+     Other keys may be added to this later.
+
    .. method:: do_execute(code, silent, store_history=True, user_expressions=None, allow_stdin=False)
    
      Execute user code.
@@ -71,6 +81,7 @@ Example
         implementation_version = '1.0'
         language = 'no-op'
         language_version = '0.1'
+        language_info = {'mimetype': 'text/plain'}
         banner = "Echo kernel - as useful as a parrot"
 
         def do_execute(self, code, silent, store_history=True, user_expressions=None,
@@ -94,7 +105,6 @@ Here's the Kernel spec ``kernel.json`` file for this::
 
     {"argv":["python","-m","echokernel", "-f", "{connection_file}"],
      "display_name":"Echo",
-     "language":"no-op"
     }
 
 
