more work on docs: #165, ci, node servers

Author: bollwyvl

azure-pipelines.yml

@@ -25,4 +25,5 @@ variables:
 jobs:
   - template: ci/job.lint.yml
   - template: ci/job.test.yml
+  - template: ci/job.docs.yml
   - template: ci/job.combine.yml

ci/job.docs.yml

@@ -0,0 +1,36 @@
+parameters:
+  platforms:
+    - name: Linux
+      vmImage: ubuntu-16.04
+      activate: source activate
+  pythons:
+    - name: ThreeSeven
+      spec: '>=3.7,<3.8.0a0'
+  env_update: conda env update -n jupyterlab-lsp --file env-test.yml --quiet
+  env_lint: conda env update -n jupyterlab-lsp --file requirements/docs.yml --quiet
+
+jobs:
+  - ${{ each platform in parameters.platforms }}:
+      - ${{ each python in parameters.pythons}}:
+          - job: Lint
+            pool:
+              vmImage: ${{ platform.vmImage }}
+            steps:
+              - template: steps.conda.yml
+                parameters:
+                  name: ${{ platform.name }}
+
+              - script: ${{ platform.activate }} && cd ci && python env_template.py "${{ python.spec }}" ">=1,<2"
+                displayName: base dependencies
+
+              - script: ${{ parameters.env_update }} || ${{ parameters.env_update }} || ${{ parameters.env_update }}
+                displayName: docs dependencies
+
+              - script: ${{ platform.activate }} jupyterlab-lsp && python scripts/docs.py
+                displayName: build docs
+
+              - task: PublishPipelineArtifact@0
+                displayName: publish docs
+                inputs:
+                  targetPath: docs/build
+                  artifactName: Docs $(Build.BuildId)

docs/Architecture.ipynb

@@ -70,8 +70,35 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### To-Be\n",
-    "Some fragments of how the architecture could change in the future, and why"
+    "### Proposals\n",
+    "Some fragments of how the architecture could change in the future, and why (or why not) they might be a good idea."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Frontend: One Socket Per Language\n",
+    "[#165](https://github.com/krassowski/jupyterlab-lsp/pull/165) proposes a single `ConnectionManager` and at most one `Connection` _per language_ instead of one of each _per document_.\n",
+    "\n",
+    "**Pro**\n",
+    "\n",
+    "- Many fewer WebSocket connections\n",
+    "\n",
+    "**Contra**\n",
+    "\n",
+    "- backwards incompatibility"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hide_input": true
+   },
+   "outputs": [],
+   "source": [
+    "%dot dot/to-be/frontend-165.dot"
    ]
   }
  ],

docs/Installation.ipynb

@@ -164,6 +164,26 @@
     "$ jupyter labextension install @krassowitz/jupyterlab-lsp\n",
     "```"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Getting NodeJS-based Language Servers\n",
+    "A number of language servers are built on the [reference implementation](https://github.com/microsoft/vscode-languageserver-node), powered by NodeJS. The most reliable place to install these is in the same folder from which you launch `jupyter lab`. For example, to install all the servers which are tested as part of `jupyterlab-lsp`:\n",
+    "\n",
+    "```bash\n",
+    "$ jlpm add \\\n",
+    "    bash-language-server \\\n",
+    "    vscode-css-languageserver-bin \\\n",
+    "    dockerfile-language-server-nodejs \\\n",
+    "    vscode-html-languageserver-bin \\\n",
+    "    javascript-typescript-langserver \\\n",
+    "    vscode-json-languageserver-bin \\\n",
+    "    yaml-language-server              \n",
+    "$ jupyter lab\n",
+    "```"
+   ]
   }
  ],
  "metadata": {

docs/_static/css/custom.css

@@ -30,3 +30,7 @@ body div.nboutput.container div[class*='highlight'] pre {
   background-color: transparent !important;
   padding: 1em;
 }
+
+.wy-nav-content {
+  max-width: 100%;
+}

docs/conf.py

@@ -59,7 +59,7 @@
     "**/.ipynb_checkpoints/**",
     "**/~.*",
     "~.*",
-    "_build/**"
+    "_build/**",
 ]
 
 pygments_style = "monokai"

docs/dot/as-is/backend.dot

@@ -1,9 +1,10 @@
 graph backend {
     label="Back End as of 0.7.0"
+    splines="line"
     fontname="sans-serif"
     node[shape=none fontname="sans-serif"]
     edge[fontname="sans-serif"]
-    graph[fontcolor=grey]
+    graph[fontcolor=grey color=grey]
     subgraph cluster_browser {
         label=Browser
         Clients

docs/dot/as-is/frontend.dot

@@ -1,9 +1,12 @@
 graph backend {
     label="Front End as of 0.7.1"
+    splines="line"
     compound=true
     fontname="sans-serif" fontcolor=grey
     node[shape=none fontname="sans-serif"]
     edge[fontname="sans-serif"]
+    graph[fontcolor=grey color=grey]
+
     subgraph cluster_io { label="IO"
         Keyboard[label="The Keyboard"]
         Mouse[label="The Mouse"]
@@ -52,6 +55,7 @@ graph backend {
     StatusBar -- Connection
     Widget -- WidgetAdapter -- Plugin -- StatusBar -- RestAPI
     Widget -- CodeMirrors
+    Plugin -- ConnectionManager
     Connection -- MessageConnection -- WebSocket -- WebSocketHandlers
     {Keyboard Mouse} -- CodeMirrors
 }

docs/dot/to-be/frontend-165.dot

@@ -0,0 +1,64 @@
+graph backend {
+    label="Front End with One Socket Per Language (#165)"
+    splines="line"
+    compound=true
+    fontname="sans-serif" fontcolor=grey
+    node[shape=none fontname="sans-serif"]
+    edge[fontname="sans-serif"]
+    graph[fontcolor=grey color=grey]
+
+    subgraph cluster_io { label="IO"
+        Keyboard[label="The Keyboard"]
+        Mouse[label="The Mouse"]
+    }
+    subgraph cluster_server { label="Server"
+        RestAPI[label="The REST API"]
+        WebSocketHandlers
+    }
+    subgraph cluster_lab { label="JupyterLab"
+        Plugin
+        StatusBar
+        WidgetTrackers
+        DiagnosticPanel
+        ConnectionManager
+             
+        subgraph cluster_lang {label="Per Language"
+            Connection
+            MessageConnection
+            WebSocket
+        }
+        subgraph cluster_doc { label="Per Document"
+            Widget
+            CodeMirrors
+            subgraph cluster_doc_lsp { label="LSP Client"
+                WidgetAdapter
+                VirtualEditor
+                VirtualDocument
+                CodeMirrorAdapters
+                subgraph cluster_features { label="Features"
+                    Feature[style=invisible]
+                    Completion
+                    Diagnostics
+                    Highlight
+                    Hover
+                    Jump
+                    Rename
+                    Signature
+                }
+            }
+        }
+    }
+    
+    {Connection CodeMirrors VirtualDocument VirtualEditor} -- Feature[lhead=cluster_features];
+    Diagnostics -- DiagnosticPanel
+    Connection -- ConnectionManager
+    CodeMirrors -- CodeMirrorAdapters -- WidgetAdapter
+    WidgetAdapter -- VirtualEditor -- VirtualDocument
+    WidgetTrackers -- {Plugin -- Widget} 
+    StatusBar -- Connection
+    Widget -- WidgetAdapter -- Plugin -- StatusBar -- RestAPI
+    Widget -- CodeMirrors
+    Plugin -- ConnectionManager
+    Connection -- MessageConnection -- WebSocket -- WebSocketHandlers
+    {Keyboard Mouse} -- CodeMirrors
+}

requirements/docs.txt

@@ -3,6 +3,7 @@
 graphviz
 nbsphinx
 recommonmark
+sphinx_autodoc_typehints
 sphinx-autobuild
 sphinx-copybutton
 sphinx-markdown-tables