Merge pull request #177 from bollwyvl/add-sphinx-docs

Start sphinx docs

Author: krassowski

.gitignore

@@ -114,4 +114,5 @@ junit.xml
 coverage/
 .vscode/
 _schema.d.ts
+_build
 .virtual_documents/

CHANGELOG.md

@@ -1,4 +1,4 @@
-# CHANGELOG
+## CHANGELOG
 
 ## `@krassowski/jupyterlab-lsp 0.8.0` (unreleased)
 
@@ -52,7 +52,7 @@
     [#164](https://github.com/krassowski/jupyterlab-lsp/pull/164)
     )
 
-## `lsp-ws-connection 0.3.1`
+### `lsp-ws-connection 0.3.1`
 
 - added `sendSaved()` method (textDocument/didSave) (
   [#147](https://github.com/krassowski/jupyterlab-lsp/pull/147)
@@ -61,7 +61,7 @@
   [#140](https://github.com/krassowski/jupyterlab-lsp/pull/140)
   )
 
-## `@krassowski/jupyterlab-lsp 0.7.0`
+### `@krassowski/jupyterlab-lsp 0.7.0`
 
 - features
 
@@ -128,7 +128,7 @@
     [#140](https://github.com/krassowski/jupyterlab-lsp/pull/140)
     )
 
-## `lsp-ws-connection 0.3.0`
+### `lsp-ws-connection 0.3.0`
 
 - infrastructure
   - brought into monorepo [#107](https://github.com/krassowski/jupyterlab-lsp/pull/107)
@@ -141,7 +141,7 @@
   - added initialization checks before executing sendChange to comply
     with LSP specs [#115](https://github.com/krassowski/jupyterlab-lsp/pull/115)
 
-## `jupyter-lsp 0.7.0b0`
+### `jupyter-lsp 0.7.0b0`
 
 - features
   - adds a language server status endpoint (
@@ -155,14 +155,14 @@
     [#100](https://github.com/krassowski/jupyterlab-lsp/pulls/100)
     )
 
-## `@krassowski/jupyterlab-lsp 0.6.1`
+### `@krassowski/jupyterlab-lsp 0.6.1`
 
 - features
   - adds an indicator to the statusbar
 - dependencies
   - removes unused npm dependencies
 
-## `@krassowski/jupyterlab-lsp 0.6.0`
+### `@krassowski/jupyterlab-lsp 0.6.0`
 
 - features
   - allows "rename" action in file editor
@@ -174,7 +174,7 @@
 - dependencies
   - requires `jupyter-lsp`
 
-## `jupyter-lsp 0.6.0b0`
+### `jupyter-lsp 0.6.0b0`
 
 - features
   - starts language servers on demand

azure-pipelines.yml

@@ -28,4 +28,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,41 @@
+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_docs: conda env update -n jupyterlab-lsp --file requirements/docs.yml --quiet
+
+jobs:
+  - ${{ each platform in parameters.platforms }}:
+      - ${{ each python in parameters.pythons}}:
+          - job: Docs
+            dependsOn:
+              - 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: generate env with python and lab version
+
+              - script: ${{ parameters.env_update }} || ${{ parameters.env_update }} || ${{ parameters.env_update }}
+                displayName: base dependencies
+
+              - script: ${{ parameters.env_docs }} || ${{ parameters.env_docs }} || ${{ parameters.env_docs }}
+                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)

ci/job.lint.yml

@@ -21,7 +21,7 @@ jobs:
                   name: ${{ platform.name }}
 
               - script: ${{ platform.activate }} && cd ci && python env_template.py "${{ python.spec }}" ">=1,<2"
-                displayName: base dependencies
+                displayName: generate env with python and lab version
 
               - script: ${{ parameters.env_update }} || ${{ parameters.env_update }} || ${{ parameters.env_update }}
                 displayName: testing dependencies

ci/job.test.yml

@@ -35,7 +35,7 @@ jobs:
                   name: ${{ platform.name }}
 
               - script: ${{ platform.activate }} && cd ci && python env_template.py "${{ python.spec }}" "${{ python.lab }}"
-                displayName: update environment with python and lab version
+                displayName: generate env with python and lab version
 
               - script: ${{ parameters.env_update }} || ${{ parameters.env_update }} || ${{ parameters.env_update }}
                 displayName: update conda environment with test dependencies

docs/Architecture.ipynb

@@ -0,0 +1,126 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Architecture"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hide_input": true
+   },
+   "outputs": [],
+   "source": [
+    "import graphviz, IPython, pathlib\n",
+    "\n",
+    "@IPython.core.magic.register_line_cell_magic\n",
+    "def dot(line, cell=None):\n",
+    "    return graphviz.Source(pathlib.Path(line).read_text() if line else cell)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### As-Is\n",
+    "These are how we _think_ everything works in the current release."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Front End"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hide_input": true
+   },
+   "outputs": [],
+   "source": [
+    "%dot dot/as-is/frontend.dot"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Backend"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hide_input": true
+   },
+   "outputs": [],
+   "source": [
+    "%dot dot/as-is/backend.dot"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 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"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

docs/EXTENDING.md

@@ -1,21 +1,21 @@
-# Extend jupyterlab-lsp and jupyter-lsp
+## Extend jupyterlab-lsp and jupyter-lsp
 
-## jupyterlab-lsp
+### jupyterlab-lsp
 
 > At present, `jupyterlab-lsp` is still in very early development, and does not
 > expose any runtime extension points. The [roadmap](./ROADMAP.md) lists several
 > potential points of extension, but will require some refactoring to achieve.
 
-## jupyter-lsp
+### jupyter-lsp
 
-### Language Server Specs
+#### Language Server Specs
 
-Language Server Specs can be [configured](./LANGUAGESERVERS.ms) by Jupyter users,
+Language Server Specs can be [configured](./LANGUAGESERVERS.md) by Jupyter users,
 or distributed by third parties as python or JSON files. Since we'd like to see
 as many Language Servers work out of the box as possible, consider
 [contributing a spec](../CONTRIBUTING.md#specs), if it works well for you!
 
-### Message Listeners
+#### Message Listeners
 
 Message listeners may choose to receive LSP messages immediately after being
 received from the client (e.g. `jupyterlab-lsp`) or a language server. All
@@ -30,13 +30,13 @@ delivery of a message, a non-blocking technique like
 
 [add_callback]: https://www.tornadoweb.org/en/stable/ioloop.html#tornado.ioloop.IOLoop.add_callback
 
-#### Add a Listener with `entry_points`
+##### Add a Listener with `entry_points`
 
 Listeners can be added via [entry_points][] by a package installed in the same
 environment as `notebook`:
 
 ```toml
-# setup.cfg
+## setup.cfg
 
 [options.entry_points]
 jupyter_lsp_listener_all_v1 =
@@ -52,12 +52,12 @@ aside from logging in the event of an error on import.
 
 [entry_points]: https://packaging.python.org/specifications/entry-points/
 
-#### Add a Listener with Jupyter Configuration
+##### Add a Listener with Jupyter Configuration
 
 Listeners can be added via `traitlets` configuration, e.g.
 
 ```yaml
-# jupyter_notebook_config.jsons
+## jupyter_notebook_config.jsons
 {
   'LanguageServerManager':
     {
@@ -68,7 +68,7 @@ Listeners can be added via `traitlets` configuration, e.g.
 }
 ```
 
-#### Add a listener with the Python API
+##### Add a listener with the Python API
 
 `lsp_message_listener` can be used as a decorator, accessed as part of a
 `serverextension`.
@@ -90,7 +90,7 @@ def load_jupyter_server_extension(nbapp):
 
 `scope` is one of `client`, `server` or `all`, and is required.
 
-#### Listener options
+##### Listener options
 
 Fine-grained controls are available as part of the Python API. Pass these as
 named arguments to `lsp_message_listener`.