Document kernel.js extensions.

docs/source/extending/frontend_extensions.rst

@@ -229,3 +229,47 @@ extension without uninstalling it.
 .. versionchanged:: 4.2
 
     Added ``--sys-prefix`` argument
+
+
+
+
+Kernel Specific extensions
+--------------------------
+
+.. warning::
+
+  This feature is only ment as a stop gap for kernels developpers whoneed
+  specific javascript to be injected on the page. The availability and api are
+  subject to change at anytime.
+
+
+It is possible to load some JavaScript on the page on a per kernel basis. Be
+aware that doing so will will make the browser page reload without warning as
+soon as the user switch kernel without warning. 
+
+As a kernel developer, if you need a specif piece of JavaScript to be loaded on
+a per kernel basis, typically if you are developing a CodeMirror mode for your
+language, or need to enable some specific debugging options, your
+``kernelspecs`` are allowed to contain a ``kernel.js`` file that define a AMD
+module. The AMD module should define an `onload` function that will be called
+when the kernel spec is loaded, that is to say when you load a notebook that
+uses your kernelspec, or change the kernelspec of a notebook to your
+kernelspec. 
+
+Note that adding a `kernel.js` to your kernelspec will add unexpected side
+effect to changing kernel. In particular, as it is impossible to "unload"
+JavaScript, any attempt to change kernelspec again will save the current
+notebook and reload the page without confirmations. 
+
+
+Here is an example of ``kernel.js``
+.. code:: javascript
+
+    // kernel.js
+
+    define(function(){
+      retrun {onload: function(){
+        console.info('Kernel specific javascript loaded');
+        // do more things here, like define a codemirror mode, 
+      }}
+    });