Update the language servers specs documentation

Author: krassowski

CONTRIBUTING.md

@@ -322,44 +322,53 @@ python scripts/lint.py
 
 ### Specs
 
-It is convenient to collect common patterns for connecting to installed language
-servers as `pip`-installable packages that Just Work with `jupyter-lsp`.
+While language servers can be configured by the user using a simple JSON or Python [configuration file](./Configuring.ipynb#language_servers),
+it is preferable to provide users with an option that does not require manual configuration. The language server specifications (specs)
+wrap the configuration (as would be defined by the user) into a Python class or function that can be either:
 
-If an advanced user installs, locates, and configures, their own language
-server it will always win vs an auto-configured one.
+- distributed using PyPI/conda-forge and made conveniently available to users for `pip install` and/or `conda install`
+- contributed to the collection of built-in specs of jupyter-lsp by opening a PR (preferable for popular language servers, say >100 users)
 
-#### Writing a spec
-
-> See the built-in [specs][] for implementations and some [helpers][].
+> If an advanced user installs, locates, and configures, their own language server it will always win vs an auto-configured one.
 
-[specs]: https://github.com/krassowski/jupyterlab-lsp/tree/master/python_packages/jupyter_lsp/jupyter_lsp/specs
-[helpers]: https://github.com/krassowski/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/specs/utils.py
+#### Writing a spec
 
-A spec is a python function that accepts a single argument, the
-`LanguageServerManager`, and returns a dictionary of the form:
+A spec is a Python callable (a function or class with `__call__` method) that accepts a single argument, the
+`LanguageServerManager` instance, and returns a dictionary of the form:
 
 ```python
 {
   "python-language-server": {            # the name of the implementation
-      "version": 1,                      # the version of the spec schema
+      "version":  SPEC_VERSION,          # the version of the spec schema (an integer)
       "argv": ["python", "-m", "pyls"],  # a list of command line arguments
       "languages": ["python"]            # a list of languages it supports
   }
 }
 ```
 
-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][] and are exercised by the current `entry_points`-based [specs][].
+The above example is only intended as an illustration and not as an up-to-date guide.
+For details on the dictionary contents, see the [schema][] definition and [built-in specs][].
+Basic concepts (meaning of the `argv` and `languages` arguments) are also explained in the [configuration files](./Configuring.ipynb#language_servers) documentation.
 
-[schema]: https://github.com/krassowski/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/schema/schema.json
+When contributing a specification we recommend to make use of the helper classes and other [utilities][] that take care of the common use-cases:
+
+- `ShellSpec` helps to create specs for servers that can be started from command-line
+- `PythonModuleSpec` is useful for servers which are Python modules
+- `NodeModuleSpec` will take care of finding Node.js modules
+
+See the built-in [specs][] for example implementations.
 
 The spec should only be advertised if the command _could actually_ be run:
 
-- its runtime (e.g. `julia`, `nodejs`, `python`, `r`, `ruby`) is installed
+- its runtime/interpreter (e.g. `julia`, `nodejs`, `python`, `r`, `ruby`) is installed
 - the language server itself is installed (e.g. `python-language-server`)
 
+otherwise an empty dictionary (`{}`) should be returned.
+
+[built-in specs]: https://github.com/krassowski/jupyterlab-lsp/tree/master/python_packages/jupyter_lsp/jupyter_lsp/specs
+[schema]: https://github.com/krassowski/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/schema/schema.json
+[utilities]: https://github.com/krassowski/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/specs/utils.py
+
 ##### Common Concerns
 
 - some language servers need to have their connection mode specified
@@ -369,8 +378,8 @@ The spec should only be advertised if the command _could actually_ be run:
   - `LanguageServerManager.nodejs` will provide the location of our best
     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][] for an example
+  - use a helper script to encapsulate some complexity, or
+  - use a command argument of the interpreter is available (see the [r spec][] and julia spec for examples)
 
 [r spec]: https://github.com/krassowski/jupyterlab-lsp/blob/master/python_packages/jupyter_lsp/jupyter_lsp/specs/r_languageserver.py
 

docs/Language Servers.ipynb

@@ -16,7 +16,7 @@
     "You can add another language server for languages that are not listed on this\n",
     "page:\n",
     "\n",
-    "- using a minimal JSON-based\n",
+    "- using a minimal JSON or Python\n",
     "  [configuration file](./Configuring.ipynb#language_servers) (good for\n",
     "  experimenting or configuring a niche server), or\n",
     "- contributing a [full specification](./Contributing.ipynb#Specs) (to enable\n",