Merge pull request #412 from karlaspuldaro/doc-update

Documentation update

Author: krassowski

CONTRIBUTING.md

@@ -27,21 +27,29 @@ You can contribute to the project through:
 
 ### Set up the environment
 
-Development requires:
+Development requires, at a minimum:
 
-- `nodejs` 10+
-- `python` 3.5+
-- `jupyterlab` 2
+- `nodejs >=10.12,<15`
+- `python >=3.6,<3.9.0a0`
+  - Python 3.6 and 3.8 are also tested on CI
+  - Python 3.6 has issues on Windows
+- `jupyterlab >=2.2.0,<3.0.0a0`
 
 It is recommended to use a virtual environment (e.g. `virtualenv` or `conda env`)
 for development.
 
+To use the same environment as the binder demo (recommended):
+
+```bash
+conda env update -n jupyterlab-lsp --file binder/environment.yml # create a conda env
+source activate jupyterlab-lsp                                   # activate it
+```
+
+Or with `pip`:
+
 ```bash
-conda env update -n jupyterlab-lsp   # create a conda env
-source activate jupyterlab-lsp       # activate it
-# or...
 pip install -r requirements/dev.txt  # in a virtualenv, probably
-                                     # ... and install nodejs, somehow
+sudo apt-get install nodejs          # ... e.g. on debian/ubuntu
 ```
 
 #### The Easy Way
@@ -168,9 +176,13 @@ Prepare the environment:
 
 ```bash
 conda env update -n jupyterlab-lsp --file requirements/atest.yml
-# or
+```
+
+or with `pip`
+
+```
 pip install -r requirements/atest.txt  # ... and install geckodriver, somehow
-apt-get install firefox-geckodriver    # ... e.g. on debian/ubuntu
+sudo apt-get install firefox-geckodriver    # ... e.g. on debian/ubuntu
 ```
 
 Run the tests:

README.md

@@ -78,8 +78,8 @@ Use context menu on rows in the panel to filter out diagnostics or copy their me
 You will need to have all of the following installed:
 
 - JupyterLab >=2.2.0,<3.0.0a0
-- Python 3.5+
-- nodejs 10+
+- Python 3.6+
+- nodejs 10.12+
 
 ## Installation
 

binder/environment.yml

@@ -6,11 +6,11 @@ channels:
 
 dependencies:
   # runtime dependencies
-  - python >=3.7,<3.8.0a0
+  - python >=3.6,<3.9.0a0
   - jupyterlab >=2.2.0,<3.0.0a0
   - notebook >=4.3.1
   # build dependencies
-  - nodejs >=10,<14
+  - nodejs >=10.12,<15
   # for python language server (and development)
   - black
   - flake8 >=3.5

binder/postBuild

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -eux
+
 # do a dev install of the server side
 python -m pip install -e . --ignore-installed --no-deps -vv
 jupyter serverextension enable --sys-prefix --py jupyter_lsp

docs/Installation.ipynb

@@ -57,14 +57,14 @@
     "- runs in your `notebook` web application on your server to handle requests from\n",
     "  the browser to _language servers_\n",
     "- to run, you need:\n",
-    "  - `python >=3.5`\n",
+    "  - `python >=3.6,<3.9.0a0`\n",
     "  - `notebook >=4.3`\n",
     "\n",
     "#### `jupyterlab-lsp`\n",
     "\n",
     "- runs in your browser, as an extension to JupyterLab\n",
     "- to install it, you need:\n",
-    "  - `nodejs >8`\n",
+    "  - `nodejs >=10.12,<15`\n",
     "  - `jupyterlab {REQUIRED_JUPYTERLAB}`\n",
     "\n",
     "#### Language Servers\n",
@@ -97,7 +97,7 @@
     "#### conda (minimal python)\n",
     "\n",
     "```bash\n",
-    "conda create -c conda-forge -n lsp 'python >=3.7,<3.8' 'jupyterlab={JUPYTERLAB_VERSION}' 'nodejs>10' 'jupyter-lsp-python={JUPYTER_LSP_VERSION}'\n",
+    "conda create -c conda-forge -n lsp 'python >=3.7,<3.8' 'jupyterlab={JUPYTERLAB_VERSION}' 'nodejs >=10.12,<15' 'jupyter-lsp-python={JUPYTER_LSP_VERSION}'\n",
     "# jupyter-lsp-python includes both the server extension (jupyter-lsp) and pyls third-party server (python-language-server)\n",
     "# if you swap it with another pre-made bundle, jupyter-lsp-r, you will get the server extension and r-languageserver;\n",
     "# alternatively, use jupyter-lsp and manually install a language server of your choice (see the table below).\n",

py_src/jupyter_lsp/README.md

@@ -1,7 +1,7 @@
 # jupyter-lsp
 
 Multi-[Language Server][language-server] WebSocket proxy for your Jupyter
-`notebook` or `lab` server. For Python 3.5+.
+`notebook` or `lab` server. For Python 3.6+.
 
 > See the parent of this repository,
 > [jupyterlab-lsp](https://github.com/krassowski/jupyterlab-lsp) for the

scripts/integrity.py

@@ -34,10 +34,12 @@
 
 REQS = ROOT / "requirements"
 BINDER = ROOT / "binder"
+BINDER_ENV = BINDER / "environment.yml"
 
 # docs
 MAIN_README = ROOT / "README.md"
 CHANGELOG = ROOT / "CHANGELOG.md"
+CONTRIBUTING = ROOT / "CONTRIBUTING.md"
 
 # TS stuff
 NPM_NS = "@krassowski"
@@ -87,6 +89,16 @@ def the_meta_package():
     )
 
 
+@pytest.fixture(scope="module")
+def the_contributing_doc():
+    return CONTRIBUTING.read_text(encoding="utf-8")
+
+
+@pytest.fixture(scope="module")
+def the_binder_env():
+    return yaml.safe_load(BINDER_ENV.read_text(encoding="utf-8"))
+
+
 @pytest.fixture(scope="module")
 def the_installation_notebook():
     """executes and loads up the installation notebook"""
@@ -185,9 +197,35 @@ def test_changelog_versions(pkg, version):
     ],
 )
 def test_installation_versions(the_installation_notebook, pkg, sep, version, expected):
+    """are the first-party versions consistent with the package metadata?"""
     assert the_installation_notebook.count(f"{pkg}{sep}{version}") == expected
 
 
+@pytest.mark.parametrize(
+    "pkg,count",
+    [
+        ["python", 2],
+        ["nodejs", 4],
+        # ["jupyterlab", 2], # this is handled through template variables
+    ],
+)
+def test_installation_env_versions(
+    the_installation_notebook, the_binder_env, pkg, count
+):
+    """are the third-party versions consistent with the binder?"""
+    for spec in the_binder_env["dependencies"]:
+        if isinstance(spec, str) and spec.startswith(f"{pkg} "):
+            assert the_installation_notebook.count(spec) == count
+
+
+@pytest.mark.parametrize("pkg", ["python", "jupyterlab", "nodejs"])
+def test_contributing_versions(the_contributing_doc, the_binder_env, pkg):
+    """are the documented contributing requirements consistent with binder?"""
+    for spec in the_binder_env["dependencies"]:
+        if isinstance(spec, str) and spec.startswith(f"{pkg} "):
+            assert spec in the_contributing_doc
+
+
 def check_integrity():
     """actually run the tests"""
     args = ["-vv", __file__]

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = jupyter-lsp
-description = Multi-Language Server WebSocket proxy for Jupyter notebook or lab server for Python 3.5+.
+description = Multi-Language Server WebSocket proxy for Jupyter Notebook/Lab server
 long_description = file: ./py_src/jupyter_lsp/README.md
 long_description_content_type = text/markdown
 url = https://github.com/krassowski/jupyterlab-lsp
@@ -26,6 +26,7 @@ package_dir =
 packages = find:
 include_package_data = True
 zip_safe = False
+python_requires = >=3.6
 
 install_requires =
     notebook >=4.3.1