Add kernel launch sequence diagram to contributors guide (#1132)

* Add kernel launch sequence diagram to contributors' guide

Co-authored-by: telamonian <[email protected]>

Author: kevin-bates

docs/doc-requirements.txt

@@ -5,6 +5,7 @@ pydata_sphinx_theme
 sphinx
 sphinx-markdown-tables
 sphinx_book_theme
+sphinxcontrib-mermaid
 sphinxcontrib-openapi
 sphinxcontrib_github_alt
 sphinxemoji

docs/source/_static/custom.css

@@ -1,3 +1,6 @@
 body div.sphinxsidebarwrapper p.logo {
   text-align: left;
 }
+.mermaid svg {
+  height: 100%;
+}

docs/source/conf.py

@@ -31,6 +31,7 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.mathjax",
     "sphinxcontrib_github_alt",
+    "sphinxcontrib.mermaid",
     "sphinxcontrib.openapi",
     "sphinxemoji.sphinxemoji",
 ]
@@ -167,6 +168,12 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    "custom.css",
+]
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.

docs/source/contributors/index.rst

@@ -21,5 +21,6 @@ These pages target people who are interested in contributing directly to the Jup
    system-architecture
    docker
    devinstall
+   sequence-diagrams
    debug
    roadmap

docs/source/contributors/sequence-diagrams.md

@@ -0,0 +1,47 @@
+# Sequence Diagrams
+
+The following consists of various sequence diagrams you might find helpful. We plan to add
+diagrams based on demand and contributions.
+
+## Kernel launch: Jupyter Lab to Enterprise Gateway
+
+This diagram depicts the interactions between components when a kernel start request
+is submitted from Jupyter Lab running against [Jupyter Server configured to use
+Enterprise Gateway](../users/connecting-to-eg.md). The diagram also includes the
+retrieval of kernel specifications (kernelspecs) prior to the kernel's initialization.
+
+```{mermaid}
+    sequenceDiagram
+        participant JupyterLab
+        participant JupyterServer
+        participant EnterpriseGateway
+        participant ProcessProxy
+        participant Kernel
+        participant ResourceManager
+        Note left of JupyterLab: fetch kernelspecs
+        JupyterLab->>JupyterServer: https GET api/kernelspecs
+        JupyterServer->>EnterpriseGateway: https GET api/kernelspecs
+        EnterpriseGateway-->>JupyterServer: api/kernelspecs response
+        JupyterServer-->>JupyterLab: api/kernelspecs response
+
+        Note left of JupyterLab: kernel initialization
+        JupyterLab->>JupyterServer: https POST api/sessions
+        JupyterServer->>EnterpriseGateway: https POST api/kernels
+        EnterpriseGateway->>ProcessProxy: launch_process()
+        ProcessProxy->>Kernel: launch kernel
+        ProcessProxy->>ResourceManager: confirm startup
+        Kernel-->>ProcessProxy: connection info
+        ResourceManager-->>ProcessProxy: state & host info
+        ProcessProxy-->>EnterpriseGateway: complete connection info
+        EnterpriseGateway->>Kernel: TCP socket requests
+        Kernel-->>EnterpriseGateway: TCP socket handshakes
+        EnterpriseGateway-->>JupyterServer: api/kernels response
+        JupyterServer-->>JupyterLab: api/sessions response
+
+        JupyterLab->>JupyterServer: ws GET api/kernels
+        JupyterServer->>EnterpriseGateway: ws GET api/kernels
+        EnterpriseGateway->>Kernel: kernel_info_request message
+        Kernel-->>EnterpriseGateway: kernel_info_reply message
+        EnterpriseGateway-->>JupyterServer: websocket upgrade response
+        JupyterServer-->>JupyterLab: websocket upgrade response
+```