Merge pull request #217 from bollwyvl/add-rtd

Add readthedocs configuration, docs updates

Author: krassowski

.readthedocs.yml

@@ -0,0 +1,11 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+conda:
+  environment: docs/rtd.yml
+
+formats:
+  - htmlzip
+  - epub

docs/Configuring.ipynb

@@ -136,7 +136,7 @@
     "\n",
     "> default: `True`\n",
     "\n",
-    "`jupyter-lsp` will look for all\n",
+    "If `True`, `jupyter-lsp` will look for all\n",
     "[known language servers](#installing-language-servers). User-configured\n",
     "`language_servers` of the same implementation will be preferred over\n",
     "`autodetect`ed ones."

docs/Installation.ipynb

@@ -15,21 +15,27 @@
     "\n",
     "Delivering LSP features to your JupyterLab **requires** three pieces:\n",
     "\n",
-    "- `jupyter_lsp`\n",
-    "  - runs in your `notebook` web application on your server\n",
-    "  - to run, you need:\n",
-    "    - `python >=3.5`\n",
-    "    - `notebook >=4.3`\n",
-    "- `jupyterlab-lsp`\n",
-    "  - runs in your browser\n",
-    "  - to install it, you need:\n",
-    "    - `nodejs >8`\n",
-    "    - `jupyterlab >=1.1,<2`\n",
-    "- one or more language servers\n",
-    "  - run on your server\n",
-    "  - some can be automatically [detected](./Language%20Servers.ipynb) if\n",
-    "    installed\n",
-    "  - others also need to be [configured](./Configuring.ipynb#language_servers)"
+    "#### `jupyter-lsp`\n",
+    "\n",
+    "- 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",
+    "  - `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",
+    "  - `jupyterlab >=1.1,<2`\n",
+    "\n",
+    "#### Language Servers\n",
+    "\n",
+    "- run on your server\n",
+    "  - probably in another language runtime than python\n",
+    "- some can be automatically [detected](./Language%20Servers.ipynb) if installed\n",
+    "- others also need to be [configured](./Configuring.ipynb#language_servers)"
    ]
   },
   {
@@ -49,11 +55,11 @@
     "#### conda (minimal python)\n",
     "\n",
     "```bash\n",
-    "conda create -c conda-forge -n lsp 'python >=3.7,<3.8' 'jupyterlab=1.2' 'nodejs=11' python-language-server\n",
+    "conda create -c conda-forge -n lsp 'python >=3.7,<3.8' 'jupyterlab=1.2' 'nodejs>8' python-language-server\n",
     "# Also consider: r-languageserver [*]\n",
     "source activate lsp\n",
-    "python -m pip install 'jupyter_lsp=0.7' --no-deps\n",
-    "jupyter labextension install '@krassowski/jupyterlab-lsp@0.7.1'\n",
+    "python -m pip install 'jupyter-lsp=0.8.0' --no-deps\n",
+    "jupyter labextension install '@krassowski/jupyterlab-lsp@0.8.0'\n",
     "```\n",
     "\n",
     "Then run\n",
@@ -91,9 +97,9 @@
     "    'python-language-server' \\\n",
     "    'r-languageserver' \\\n",
     "  && python3 -m pip install --no-cache-dir --no-deps \\\n",
-    "    'jupyter_lsp==0.7' \\\n",
+    "    'jupyter-lsp=0.8.0' \\\n",
     "  && jupyter labextension install --no-build \\\n",
-    "    '@krassowski/jupyterlab-lsp@0.7.1' \\\n",
+    "    '@krassowski/jupyterlab-lsp@0.8.0' \\\n",
     "  && jupyter lab build --dev-build=False --minimize=True \\\n",
     "  && conda clean --all -f -y \\\n",
     "  && rm -rf \\\n",
@@ -201,8 +207,8 @@
     "#### Install Jupyter[Lab] LSP\n",
     "\n",
     "```bash\n",
-    "pip install jupyter_lsp\n",
-    "jupyter labextension install @krassowitz/jupyterlab-lsp\n",
+    "pip install jupyter-lsp=0.8.0\n",
+    "jupyter labextension install @krassowski/jupyterlab-lsp@0.8.0\n",
     "```"
    ]
   },
@@ -212,12 +218,12 @@
    "source": [
     "### Next Step: Language Servers\n",
     "\n",
-    "Now that you have `jupyterlab-lsp`, `jupyter_lsp` and all of their dependencies,\n",
+    "Now that you have `jupyterlab-lsp`, `jupyter-lsp` and all of their dependencies,\n",
     "you'll need some language servers. See:\n",
     "\n",
     "- [Language Servers](./Language%20Servers.ipynb) that will be found\n",
     "  automatically once installed\n",
-    "- [configuring](./Configuring.ipynb) `jupyter_lsp` for more control over which\n",
+    "- [configuring](./Configuring.ipynb) `jupyter-lsp` for more control over which\n",
     "  servers to load"
    ]
   }

docs/Language Servers.ipynb

@@ -11,8 +11,8 @@
     "servers in the tables below, use one of the suggested package managers to\n",
     "install them: these implementations are tested to work with `jupyter-lsp`.\n",
     "\n",
-    "> _You can disable this feature by configuring_ >\n",
-    "> _[autodetect](./Configuring.ipynb#autodetect)_\n",
+    "- _You can disable this feature by configuring_\n",
+    "  [autodetect](./Configuring.ipynb#autodetect)\n",
     "\n",
     "If you do not see a language you would like, but can find it one of these lists:\n",
     "\n",

docs/Releasing.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "## Releasing\n",
     "\n",
-    "`jupyterlab-lsp` and `jupyter_lsp` releases may require building both the python\n",
+    "`jupyterlab-lsp` and `jupyter-lsp` releases may require building both the python\n",
     "package and nodejs packages."
    ]
   },
@@ -22,8 +22,8 @@
     "python scripts/integrity.py\n",
     "```\n",
     "\n",
-    "> TODO: create a `release.py` script\n",
-    "> [#88](https://github.com/krassowski/jupyterlab-lsp/issues/88)\n",
+    "- TODO: create a `release.py` script\n",
+    "  [#88](https://github.com/krassowski/jupyterlab-lsp/issues/88)\n",
     "\n",
     "The PyPI version must be updated in the following places:\n",
     "\n",

docs/conf.py

@@ -3,6 +3,7 @@
 # pylint: disable=invalid-name,redefined-builtin,import-error
 
 import pathlib
+import subprocess
 import sys
 
 import nbsphinx
@@ -105,3 +106,4 @@ def setup(app):
     """ Runs before the "normal business" of sphinx. Don't go too crazy here.
     """
     app.add_css_file("css/custom.css")
+    subprocess.check_call(["jlpm", "--ignore-optional"])

docs/rtd.yml

@@ -0,0 +1,22 @@
+# minimal possible conda env for modern nodejs
+name: jupyterlab-lsp-docs
+
+dependencies:
+  - nodejs
+  - pip
+  - python >=3.8,<3.9.0a0
+  - pip:
+      - -e ..
+      - graphviz
+      - importlib_metadata
+      - jupyterlab >=1,<1.3.0a0
+      - nbsphinx >=0.5.0,<0.5.1a0
+      - pandas
+      - pytest-check-links
+      - python-language-server
+      - recommonmark
+      - sphinx
+      - sphinx_rtd_theme
+      - sphinx-autodoc-typehints
+      - sphinx-copybutton
+      - sphinx-markdown-tables

py_src/jupyter_lsp/specs/utils.py

@@ -1,3 +1,4 @@
+import os
 import shutil
 from pathlib import Path
 from typing import List, Text
@@ -12,6 +13,9 @@
 # helper scripts for known tricky language servers
 HELPERS = Path(__file__).parent / "helpers"
 
+# when building docs, let all specs go through
+BUILDING_DOCS = os.environ.get("JUPYTER_LSP_BUILDING_DOCS") is not None
+
 
 class SpecBase:
     """ Base for a spec finder that returns a spec for starting a language server
@@ -41,6 +45,9 @@ def __call__(self, mgr: LanguageServerManagerAPI) -> KeyedLanguageServerSpecs:
             if cmd:
                 break
 
+        if not cmd and BUILDING_DOCS:  # pragma: no cover
+            cmd = self.cmd
+
         if not cmd:  # pragma: no cover
             return {}
 

scripts/integrity.py

@@ -58,6 +58,7 @@
 PIPE_FILE = ROOT / "azure-pipelines.yml"
 PIPELINES = yaml.safe_load(PIPE_FILE.read_text())
 PIPE_VARS = PIPELINES["variables"]
+DOCS = ROOT / "docs"
 
 CI = ROOT / "ci"
 
@@ -80,6 +81,13 @@ def the_meta_package():
     )
 
 
+@pytest.fixture(scope="module")
+def the_installation_notebook():
+    """ loads up the installation notebook
+    """
+    return (DOCS / "Installation.ipynb").read_text()
+
+
 @pytest.mark.parametrize(
     "name,version",
     [["PY_JLSP_VERSION", PY_VERSION], ["JS_JLLSP_VERSION", MAIN_EXT_VERSION]],
@@ -141,6 +149,14 @@ def test_changelog_versions(pkg, version):
     assert "## `{} {}`".format(pkg, version) in CHANGELOG.read_text()
 
 
+@pytest.mark.parametrize(
+    "pkg,sep,version,expected",
+    [[PY_NAME, "=", PY_VERSION, 3], [MAIN_NAME, "@", MAIN_EXT_VERSION, 3]],
+)
+def test_installation_versions(the_installation_notebook, pkg, sep, version, expected):
+    assert the_installation_notebook.count(f"{pkg}{sep}{version}") == expected
+
+
 def check_integrity():
     """ actually run the tests
     """