Some docs cleanup

.github/ISSUE_TEMPLATE/feature_request.md

@@ -6,7 +6,7 @@ about: Help us build future features
 <!--
 Welcome! Before creating a new issue:
 * Search for relevant issues
-* Look at ROADMAP.md to make sure we don't already want the same thing
+* Look at docs/Roadmap.ipynb to make sure we don't already want the same thing
 * Follow the issue reporting guidelines:
 https://jupyterlab.readthedocs.io/en/latest/getting_started/issue.html
 -->

.github/ISSUE_TEMPLATE/intent_to_implement.md

@@ -6,7 +6,7 @@ about: Announce that you're going to do some work
 <!--
 Welcome! Before creating a new issue:
 * Search for relevant issues
-* Look at ROADMAP.md to make sure we don't already want the same thing
+* Look at docs/Roadmap.ipynb to make sure we don't already want the same thing
 * Follow the issue reporting guidelines:
 https://jupyterlab.readthedocs.io/en/latest/getting_started/issue.html
 -->

.prettierignore

@@ -1,32 +1,33 @@
-node_modules
-**/node_modules
-**/lib
+.eggs
+.mypy_cache
+.pytest_cache
+.yarn-packages
+**/.ipynb_checkpoints
+**/*.egg-info
 **/build
 **/dist
+**/lib
+**/node_modules
+**/package.json
 **/static
-jupyterlab/schemas
-jupyterlab/themes
-jupyterlab/geckodriver
-jupyterlab/staging/yarn.js
-jupyterlab/staging/index.js
+atest
+coverage
 dev_mode/index.js
 dev_mode/schemas
 dev_mode/static
 dev_mode/themes
 dev_mode/workspaces
-examples/app/build
-examples/app/themes
-examples/app/schemas
-tests/**/coverage
 docs/_build
+docs/_templates
 docs/api
-**/package.json
-.eggs
 envs
-.mypy_cache
-.pytest_cache
-**/.ipynb_checkpoints
-**/*.egg-info
-.yarn-packages
-atest
-coverage
+examples/app/build
+examples/app/schemas
+examples/app/themes
+jupyterlab/geckodriver
+jupyterlab/schemas
+jupyterlab/staging/index.js
+jupyterlab/staging/yarn.js
+jupyterlab/themes
+node_modules
+tests/**/coverage

.travis.yml

@@ -11,7 +11,7 @@ matrix:
     - python: '3.5'
     - python: '3.6'
     - python: '3.7'
-    - python: '3.8-dev'
+    - python: '3.8'
     - os: osx
       osx_image: xcode11
       language: shell

CHANGELOG.md

@@ -1,6 +1,6 @@
 ## CHANGELOG
 
-## `@krassowski/jupyterlab-lsp 0.8.0` (unreleased)
+### `@krassowski/jupyterlab-lsp 0.8.0` (unreleased)
 
 - features
 
@@ -11,7 +11,7 @@
   - ignores malformed diagnostic ranges, enabling markdown support ([#165][])
   - passes tests on Python 3.8 on Windows ([#165][])
 
-## `lsp-ws-connection 0.4.0` (unreleased)
+### `lsp-ws-connection 0.4.0` (unreleased)
 
 - breaking changes
 
@@ -22,14 +22,14 @@
 
 [#165]: https://github.com/krassowski/jupyterlab-lsp/pull/165
 
-## `jupyter-lsp 0.7.0`
+### `jupyter-lsp 0.7.0`
 
 - bugfixes
   - didSave no longer causes unwanted messages in logs (
     [#187](https://github.com/krassowski/jupyterlab-lsp/pull/187)
     )
 
-## `@krassowski/jupyterlab-lsp 0.7.1`
+### `@krassowski/jupyterlab-lsp 0.7.1`
 
 - features
 
@@ -159,14 +159,14 @@
 
 - features
   - adds an indicator to the statusbar
+  - and many other improvements, see the [release notes](https://github.com/krassowski/jupyterlab-lsp/releases/tag/v0.6.1)
 - dependencies
   - removes unused npm dependencies
 
 ### `@krassowski/jupyterlab-lsp 0.6.0`
 
 - features
   - allows "rename" action in file editor
-  - and many other improvements, see the [release notes](https://github.com/krassowski/jupyterlab-lsp/releases/tag/v0.6.0)
 - bugfixes
   - handles some non-standard diagnostic responses
 - testing

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contribute to jupyterlab-lsp and jupyter-lsp :heart:
+## Contribute to jupyterlab-lsp and jupyter-lsp :heart:
 
-`jupyter-lsp` and `jupyterlab-lsp` are [open source](./LICENSE) software, and
+`jupyter-lsp` and `jupyterlab-lsp` are [open source][license] software, and
 all contributions conforming to good sense, good taste, and the
 [Jupyter Code of Conduct][code-of-conduct] are welcome, and will be reviewed
 by the contributors, time-permitting.
@@ -13,16 +13,19 @@ You can contribute to the project through:
     and its various distributions
     - these are great first issues, as you might not need to know any python or
       javascript
-- proposing parts of the architecture that can be [extended](./docs/EXTENDING.md)
+- proposing parts of the architecture that can be [extended][extending]
 - improving [documentation](#Documentation)
-- tackling Big Issues from the [future roadmap](./docs/ROADMAP.md)
+- tackling Big Issues from the [future roadmap][roadmap]
 - improving [testing](#Testing)
 - reviewing pull requests
 
+[license]: https://github.com/krassowski/jupyterlab-lsp/blob/master/LICENSE
+[extending]: ./docs/Extending.ipynb
+[roadmap]: ./docs/Roadmap.ipynb
 [jupyterlab-lsp]: https://github.com/krassowski/jupyterlab-lsp.git
 [code-of-conduct]: https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md
 
-## Set up the environment
+### Set up the environment
 
 Development requires:
 
@@ -41,7 +44,7 @@ pip install -r requirements/dev.txt  # in a virtualenv, probably
                                      # ... and install nodejs, somehow
 ```
 
-### The Easy Way
+#### The Easy Way
 
 Once your environment is created and activated, on Linux/OSX you can run:
 
@@ -51,7 +54,7 @@ bash postBuild
 
 This performs all of the basic setup steps, and is used for the binder demo.
 
-### The Hard Way
+#### The Hard Way
 
 Install `jupyter-lsp` from source in your virtual environment:
 
@@ -74,7 +77,7 @@ jlpm build
 jlpm lab:link
 ```
 
-## Frontend Development
+### Frontend Development
 
 To rebuild the schemas, packages, and the JupyterLab app:
 
@@ -110,15 +113,44 @@ To run tests matching specific phrase, forward `-t` argument over yarn and lerna
 jlpm test -- -- -t match_phrase
 ```
 
-## Server Development
+### Server Development
 
-### Testing `jupyter-lsp`
+#### Testing `jupyter-lsp`
 
 ```bash
 python scripts/utest.py
 ```
 
-## Browser-based Acceptance Tests
+### Documentation
+
+To build the documentation:
+
+```bash
+python scripts/docs.py
+```
+
+To watch documentation sources and build continuously:
+
+```bash
+python scripts/docs.py --watch
+```
+
+To check internal links in the docs after building:
+
+```bash
+python scripts/docs.py --check --local-only
+```
+
+To check internal _and_ external links in the docs after building:
+
+```bash
+python scripts/docs.py --check
+```
+
+> Note: you may get spurious failures due to rate limiting, especially in CI,
+> but it's good to test locally
+
+### Browser-based Acceptance Tests
 
 The browser tests will launch JupyterLab on a random port and exercise the
 Language Server features with [Robot Framework][] and [SeleniumLibrary][]. It
@@ -217,7 +249,7 @@ python scripts/combine.py
 
 - If you see the following error message:
 
-  ```
+  ```python
   Parent suite setup failed:
   TypeError: expected str, bytes or os.PathLike object, not NoneType
   ```
@@ -226,7 +258,9 @@ python scripts/combine.py
   in the search path).
 
 - If a test suite for a specific language fails it may indicate that you have no
-  appropriate server language installed (see [LANGUAGESERVERS.md](./LANGUAGESERVERS.md))
+  appropriate server language installed (see [LANGUAGESERVERS][])
+
+[languageservers]: ./docs/Language%20Servers.ipynb
 
 - If you are seeing errors like `Element is blocked by .jp-Dialog`, caused by
   the JupyterLab _Build suggested_ dialog, (likely if you have been using
@@ -257,18 +291,6 @@ You can clean up your code, and check for using the project's style guide with:
 python scripts/lint.py
 ```
 
-> TBD
->
-> - hypothesis
-> - mypy
-
-## Documentation
-
-> TBD
->
-> - sphinx
-> - one of the sphinx/ipynb connectors
-
 ### Specs
 
 It is convenient to collect common patterns for connecting to installed language
@@ -279,8 +301,10 @@ server it will always win vs an auto-configured one.
 
 #### Writing a spec
 
-> See the built-in [specs](./py_src/jupyter_lsp/specs) for implementations and some
-> [helpers](./py_src/jupyter_lsp/specs/utils.py).
+> See the built-in [specs][] for implementations and some [helpers][].
+
+[specs]: https://github.com/krassowski/jupyterlab-lsp/tree/master/py_src/jupyter_lsp/specs
+[helpers]: https://github.com/krassowski/jupyterlab-lsp/blob/master/py_src/jupyter_lsp/specs/utils.py
 
 A spec is a python function that accepts a single argument, the
 `LanguageServerManager`, and returns a dictionary of the form:
@@ -298,8 +322,9 @@ A spec is a python function that accepts a single argument, the
 The absolute minimum listing requires `argv` (a list of shell tokens to launch
 the server) and `languages` (which languages to respond to), but many number of
 other options to enrich the user experience are available in the
-[schema](./py_src/jupyter_lsp/schema/schema.json) and are exercised by the
-current `entry_points`-based [specs]().
+[schema][] and are exercised by the current `entry_points`-based [specs][].
+
+[schema]: https://github.com/krassowski/jupyterlab-lsp/blob/master/py_src/jupyter_lsp/schema/schema.json
 
 The spec should only be advertised if the command _could actually_ be run:
 
@@ -316,7 +341,9 @@ The spec should only be advertised if the command _could actually_ be run:
     guess at where a user's `nodejs` might be found
 - some language servers are hard to start purely from the command line
   - use a helper script to encapsulate some complexity.
-    - See the [r spec](./py_src/jupyter_lsp/specs/r_languageserver.py) for an example
+    - See the [r spec][] for an example
+
+[r spec]: https://github.com/krassowski/jupyterlab-lsp/blob/master/py_src/jupyter_lsp/specs/r_languageserver.py
 
 ##### Example: making a pip-installable `cool-language-server` spec
 

LANGUAGESERVERS.md

@@ -1 +1 @@
-This file has moved to [docs/LANGUAGESERVERS.md](./docs/LANGUAGESERVERS.md).
+This file has moved to [docs/LANGUAGESERVERS.md](./docs/Configuring.ipynb).

README.md

@@ -4,11 +4,11 @@
 
 > _This project is still maturing, but you are welcome to check it out, leave feedback and/or a PR_
 
-Quick Links: **[Installation](#installation) | [Language Servers](./docs/LANGUAGESERVERS.md) | [Updating](#updating) | [Changelog](./CHANGELOG.md) | [Roadmap](./docs/ROADMAP.md) | [Contributing](./CONTRIBUTING.md) | [Extending](./docs/EXTENDING.md)**
+Quick Links: **[Installation](./Installation.ipynb) | [Configuring](./docs/Configuring.ipynb) | [Updating](#updating) | [Changelog](./CHANGELOG.md) | [Roadmap](./docs/Roadmap.ipynb) | [Contributing](./CONTRIBUTING.md) | [Extending](./docs/Extending.ipynb)**
 
 ## Features
 
-> Examples show Python code, but most features also work in R, bash, typescript and [many other languages](./docs/LANGUAGESERVERS.md).
+> Examples show Python code, but most features also work in R, bash, typescript, and [many other languages](./docs/Language Servers.ipynb).
 
 ### Hover
 

ci/job.docs.yml

@@ -31,6 +31,12 @@ jobs:
               - script: ${{ parameters.env_docs }} || ${{ parameters.env_docs }} || ${{ parameters.env_docs }}
                 displayName: docs dependencies
 
+              - script: ${{ platform.activate }} jupyterlab-lsp &&  jlpm || jlpm || jlpm
+                displayName: install npm dependencies (for language servers)
+
+              - script: ${{ platform.activate }} jupyterlab-lsp && python -m pip install -e . --no-deps --ignore-installed
+                displayName: dev install python (for introspection)
+
               - script: ${{ platform.activate }} jupyterlab-lsp && python scripts/docs.py
                 displayName: build docs
 
@@ -39,3 +45,6 @@ jobs:
                 inputs:
                   targetPath: docs/_build
                   artifactName: Docs $(Build.BuildId)
+
+              - script: ${{ platform.activate }} jupyterlab-lsp && python scripts/docs.py --check --local-only
+                displayName: check local URLs in docs