Merge pull request #581 from krassowski/myst

Switch to MyST and MyST-{NB} with book-theme

Author: krassowski

CHANGELOG.md

@@ -1,4 +1,4 @@
-## CHANGELOG
+## Changelog
 
 ### `@krassowski/jupyterlab-lsp 3.5.1` (unreleased)
 

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Contribute to jupyterlab-lsp and jupyter-lsp :heart:
+## Contributing
 
 `jupyter-lsp` and `jupyterlab-lsp` are [open source][license] software, and
 all contributions conforming to good sense, good taste, and the
@@ -19,9 +19,11 @@ You can contribute to the project through:
 - improving testing
 - reviewing pull requests
 
+Thank you for all your contributions :heart:
+
 [license]: https://github.com/krassowski/jupyterlab-lsp/blob/master/LICENSE
-[extending]: ./docs/Extending.ipynb
-[roadmap]: ./docs/Roadmap.ipynb
+[extending]: ./docs/Extending.html
+[roadmap]: ./docs/Roadmap.html
 [jupyterlab-lsp]: https://github.com/krassowski/jupyterlab-lsp.git
 [code-of-conduct]: https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md
 
@@ -328,7 +330,7 @@ python scripts/lint.py
 
 ### Specs
 
-While language servers can be configured by the user using a simple JSON or Python [configuration file](./Configuring.ipynb#language_servers),
+While language servers can be configured by the user using a simple JSON or Python [configuration file](./Configuring.html#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:
 
@@ -357,7 +359,7 @@ A spec is a Python callable (a function, or a class with `__call__` method) that
 
 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.
+Basic concepts (meaning of the `argv` and `languages` arguments) are also explained in the [configuration files](./Configuring.html#language-servers) documentation.
 
 When contributing a specification we recommend to make use of the helper classes and other [utilities][] that take care of the common use-cases:
 

docs/Architecture.ipynb

@@ -11,7 +11,9 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "hide_input": true
+    "tags": [
+     "remove-cell"
+    ]
    },
    "outputs": [],
    "source": [
@@ -49,7 +51,9 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "hide_input": true
+    "tags": [
+     "remove-input"
+    ]
    },
    "outputs": [],
    "source": [
@@ -76,7 +80,9 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "hide_input": true
+    "tags": [
+     "remove-input"
+    ]
    },
    "outputs": [],
    "source": [

docs/CHANGELOG.ipynb

@@ -2,27 +2,13 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Changelog"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {
-    "hide_input": true
+    "tags": []
    },
-   "outputs": [],
    "source": [
-    "# this re-prints CHANGELOG.md, which is valuable to have in the root of the repo\n",
-    "\n",
-    "import pathlib\n",
-    "\n",
-    "import IPython\n",
+    "```{include} ../CHANGELOG.md\n",
     "\n",
-    "contrib = pathlib.Path(\"../CHANGELOG.md\").read_text().split(\"\\n\", 1)[1]\n",
-    "IPython.display.Markdown(contrib)"
+    "```"
    ]
   }
  ],

docs/Configuring.ipynb

@@ -42,14 +42,14 @@
     "#### language_servers\n",
     "\n",
     "`jupyter-lsp` does not come with any Language Servers! However, we will try to\n",
-    "use [known language servers](./Language%20Servers.ipynb) if they _are_ installed\n",
+    "use [known language servers](./Language%20Servers.html) if they _are_ installed\n",
     "and we know about them: you can disable this behavior by configuring\n",
     "[autodetect](#autodetect).\n",
     "\n",
     "If you don't see an implementation for the language server you need, continue\n",
     "reading!\n",
     "\n",
-    "> Please consider [contributing your language server spec](./Contributing.ipynb)\n",
+    "> Please consider [contributing your language server spec](./Contributing.html)\n",
     "> to `jupyter-lsp`!"
    ]
   },
@@ -68,12 +68,12 @@
     "    get such an array.\n",
     "- the `languages` which the language server will respond to, and\n",
     "- the schema `version` of the spec (currently `2`)\n",
-    "- `mime_types` by which the notebooks and files will be matched to the langauge\n",
+    "- `mime_types` by which the notebooks and files will be matched to the language\n",
     "  server:\n",
     "  - for notebooks the MIME type is derived from `language_info`/`mimetype`\n",
     "    element of [kernel_info][] response (with fallback on to cell metadata if\n",
     "    missing from kernel response)\n",
-    "  - for files the implemntation is frontend-specific; in JupyterLab the MIME\n",
+    "  - for files the implementation is frontend-specific; in JupyterLab the MIME\n",
     "    type is obtained from the MIME type registry.\n",
     "\n",
     "```python\n",
@@ -157,7 +157,7 @@
     "> default: `True`\n",
     "\n",
     "If `True`, `jupyter-lsp` will look for all\n",
-    "[known language servers](./Language%20Servers.ipynb). User-configured\n",
+    "[known language servers](./Language%20Servers.html). User-configured\n",
     "`language_servers` of the same implementation will be preferred over\n",
     "`autodetect`ed ones."
    ]
@@ -215,11 +215,36 @@
     "`pip`-installable packages in the same environment as the Jupyter server can be\n",
     "automatically detected as providing [language_servers](#language_servers). These\n",
     "are a little more involved, but also more powerful: see more in\n",
-    "[Contributing](Contributing.ipynb#Specs). Servers configured this way are loaded\n",
+    "[Contributing](Contributing.html#Specs). Servers configured this way are loaded\n",
     "_before_ those defined in [configuration files](#Configuration-Files), so that a\n",
     "user can fine-tune their available servers."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Making Custom Servers Work With Notebooks\n",
+    "\n",
+    "To enable integration of language servers with Jupyter notebooks this extensions\n",
+    "assumes that the `language_info` section of [`kernel_info_reply`][kernel_info]\n",
+    "is complete and properly returned by the Kernel. In particular the following\n",
+    "elements are required:\n",
+    "\n",
+    "- **File extension**: many language servers only handle files with specific file\n",
+    "  extensions and refuse to operate if not provided with such; the file extension\n",
+    "  of a native script for a given language (this is other than `.ipynb`), derived\n",
+    "  from `file_extension` field of `language_info`, will be added to the name of\n",
+    "  the notebook when communicating with the language server to satisfy the file\n",
+    "  extension check.\n",
+    "- **MIME type**: matching of notebooks to servers is based on the MIME types\n",
+    "  declared in server specification files and `mimetype` field of\n",
+    "  `language_info`. If kernel fails to provide any MIME type, connecting the\n",
+    "  language server will not be possible; if multiple MIME types are in use, any\n",
+    "  would work well for this extension as long as you also include it in the\n",
+    "  `mime_types` list of language server specification."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

docs/Contributing.ipynb

@@ -4,27 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Contributing"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "hide_input": true
-   },
-   "outputs": [],
-   "source": [
-    "# this re-prints CONTRIBUTING.md, which is valuable to have in the root of the repo\n",
-    "\n",
-    "import pathlib\n",
-    "import re\n",
-    "\n",
-    "import IPython\n",
+    "```{include} ../CONTRIBUTING.md\n",
     "\n",
-    "contrib = pathlib.Path(\"../CONTRIBUTING.md\").read_text().split(\"\\n\", 1)[1]\n",
-    "contrib = re.sub(r\"^\\[(.*)\\]: \\./docs/(.*)$\", \"[\\\\1]: ./\\\\2\", contrib, flags=re.M)\n",
-    "IPython.display.Markdown(contrib)"
+    "```"
    ]
   }
  ],

docs/Extending.ipynb

@@ -169,10 +169,10 @@
     "\n",
     "### Language Server Specs\n",
     "\n",
-    "Language Server Specs can be [configured](./Configuring.ipynb) by Jupyter users,\n",
+    "Language Server Specs can be [configured](./Configuring.html) by Jupyter users,\n",
     "or distributed by third parties as python or JSON files. Since we'd like to see\n",
     "as many Language Servers work out of the box as possible, consider\n",
-    "[contributing a spec](./Contributing.ipynb#specs), if it works well for you!"
+    "[contributing a spec](./Contributing.html#specs), if it works well for you!"
    ]
   },
   {