diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 178cb31ea..f7a3e6b61 100644 --- a/azure-pipelines.yml +++ b/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 diff --git a/ci/job.docs.yml b/ci/job.docs.yml new file mode 100644 index 000000000..340c65e1d --- /dev/null +++ b/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) diff --git a/docs/Architecture.ipynb b/docs/Architecture.ipynb index ad7588e37..b810d1337 100644 --- a/docs/Architecture.ipynb +++ b/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" ] } ], diff --git a/docs/Installation.ipynb b/docs/Installation.ipynb index 702595842..0d31ed4b1 100644 --- a/docs/Installation.ipynb +++ b/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": { diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 4669f619e..a8434d5e7 100644 --- a/docs/_static/css/custom.css +++ b/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%; +} diff --git a/docs/conf.py b/docs/conf.py index 67b4368cc..280eed8cf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,7 +59,7 @@ "**/.ipynb_checkpoints/**", "**/~.*", "~.*", - "_build/**" + "_build/**", ] pygments_style = "monokai" diff --git a/docs/dot/as-is/backend.dot b/docs/dot/as-is/backend.dot index f1d872e53..e2ecd4277 100644 --- a/docs/dot/as-is/backend.dot +++ b/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 diff --git a/docs/dot/as-is/frontend.dot b/docs/dot/as-is/frontend.dot index b91c05839..da59d3003 100644 --- a/docs/dot/as-is/frontend.dot +++ b/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 } \ No newline at end of file diff --git a/docs/dot/to-be/frontend-165.dot b/docs/dot/to-be/frontend-165.dot new file mode 100644 index 000000000..adce59269 --- /dev/null +++ b/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 +} \ No newline at end of file diff --git a/requirements/docs.txt b/requirements/docs.txt index 57dad1cb0..0700d7f0d 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -3,6 +3,7 @@ graphviz nbsphinx recommonmark +sphinx_autodoc_typehints sphinx-autobuild sphinx-copybutton sphinx-markdown-tables