Some docs cleanup

.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.md
+[roadmap]: ./docs/ROADMAP.md
 [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/LANGUAGESERVERS.md
 
 - 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
 

ci/job.docs.yml

@@ -39,3 +39,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