Enrich Docs with Usage

docs/conf.py

@@ -41,12 +41,6 @@
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
 
-# Jupyter uses recommonmark's parser to convert markdown
-source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
-}
-
-
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 

docs/environment.yml

@@ -3,11 +3,8 @@ channels:
   - conda-forge
 dependencies:
 - pyzmq
-- python==3.5
+- python==3.7
 - traitlets>=4.1
 - jupyter_core
 - sphinx>=1.3.6
 - sphinx_rtd_theme
-- pip:
-    - recommonmark
-    - sphinx-markdown-tables

docs/kernel_providers.rst

@@ -135,6 +135,8 @@ above).
 
     # Use `manager` for lifecycle management, `client` for communication
 
+.. _included_kernel_providers:
+
 Included kernel providers
 =========================
 

docs/server.rst

@@ -0,0 +1,40 @@
+.. _server:
+
+=======================
+Use with Jupyter Server
+=======================
+
+This page describes the way `Jupyter Server <https://github.com/jupyter/jupyter_server>`_ uses the Kernel Management module.
+
+.. image:: ./images/kernel_mgmt_server.svg
+
+On the Jupyter Server side, each WEB handlers located in services/kernels/handlers: 
+
+- MainKernelHandler
+- KernelHandler
+- KernelActionHandler
+- ZMQChannelHandler
+- MainKernelSpecHandler
+
+Each of these handlers have:
+
+- A ``kernel_manager`` - the default manager is `MappingKernelManager` provided by `jupyter_server`.
+- A ``kernel_finder`` - which is imported from the `jupyter_kernel_mgmt` library
+
+Jupyter Server runs with a single `ServerApp` built around a ``SessionManager``. The SessionManager uses a ``MappingKernelManager``. All instances of MappingKernelManager have a ``KernelFinder``.
+
+The :ref:`included kernel providers <included_kernel_providers>` (:class:`KernelSpecProvider <jupyter_kernel_mgmt.discovery.KernelSpecProvider>` and :class:`IPykernelProvider <jupyter_kernel_mgmt.discovery.IPykernelProvider>`) register their entrypoints.
+
+.. code-block:: python
+
+  entrypoints:
+    jupyter_kernel_mgmt.kernel_type_providers' : [
+      'spec = jupyter_kernel_mgmt.discovery:KernelSpecProvider',
+      'pyimport = jupyter_kernel_mgmt.discovery:IPykernelProvider',
+    ]
+
+External Providers can register their own entypoints, e.g the `kubernetes_kernel_provider <https://github.com/gateway-experiments/kubernetes_kernel_provider>`_ which extends the `remote_kernel_provider <https://github.com/gateway-experiments/remote_kernel_provider>`_.
+
+The interactions sequence between Jupyter Server and the Kernel Management is sketched here.
+
+.. image:: ./images/kernel_mgmt_server_sequence.svg

docs/standalone.rst

@@ -0,0 +1,14 @@
+.. _standalone:
+
+================
+Standalone Usage
+================
+
+The aim of the Kernel Management is to be integrated in larger application such as the :ref:`Jupyter Server <server>`.
+
+Although, it can be used a standalone module to, for example, launch a :ref:`Kernel Finder <kernel_finder>`
+from the command line and get a list of :ref:`Kernel Specifications <kernelspecs>`
+
+.. code-block:: python
+
+    python -m jupyter_kernel_mgmt.discovery