{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [],
   "source": [
    "import sys\n",
    "\n",
    "from format_markdown import markdown\n",
    "\n",
    "sys.path.insert(0, \"..\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [],
   "source": [
    "from versions import (\n",
    "    JUPYTER_LSP_VERSION,\n",
    "    JUPYTERLAB_LSP_VERSION,\n",
    "    JUPYTERLAB_NEXT_MAJOR_VERSION,\n",
    "    JUPYTERLAB_VERSION,\n",
    "    REQUIRED_JUPYTER_SERVER,\n",
    "    REQUIRED_JUPYTERLAB,\n",
    "    REQUIRED_PYTHON,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "### Please Read This First\n",
    "\n",
    "Delivering LSP features to your JupyterLab **requires** three pieces:\n",
    "\n",
    "#### 1. `jupyter-lsp`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-input"
    ]
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "- runs in your `jupyter_server` application on your server to handle requests from\n",
    "  the browser to _language servers_\n",
    "- to run, you need:\n",
    "  - `python {REQUIRED_PYTHON}`\n",
    "  - `jupyter_server {REQUIRED_JUPYTER_SERVER}`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "#### 2. `jupyterlab-lsp`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-input"
    ]
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "- runs in your browser, as an extension to JupyterLab\n",
    "- to install it, you need:\n",
    "  - `jupyterlab {REQUIRED_JUPYTERLAB}`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "#### 3. Language Servers\n",
    "\n",
    "- run on your server\n",
    "  - probably in another language runtime than python\n",
    "- some can be automatically [detected](./Language%20Servers.html) if installed\n",
    "- others also need to be [configured](./Configuring.html#language_servers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Clean installation\n",
    "\n",
    "The approaches demonstrated below will ensure that correct versions of Python,\n",
    "JupyterLab and extensions are installed, and are generally recommended for\n",
    "novice users, or users who are not familiar with the Python ecosystem. However,\n",
    "if you feel proficient with using Python package managers such as `pip` and\n",
    "`conda` you may prefer to follow the [custom installation](#custom-installation)\n",
    "guide instead, which allows to install the packages in an existing environment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "#### conda (minimal python)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When installing from conda-forge, the `jupyter-lsp-python` bundle includes both\n",
    "the server extension (`jupyter-lsp`) and `pyls` (a third-party server also known\n",
    "as `python-language-server`). You can swap `jupyter-lsp-python` with another\n",
    "pre-made bundle, `jupyter-lsp-r` to get get the same server extension but with\n",
    "`r-languageserver` instead. Alternatively, you can install a language server of\n",
    "your choice manually (see further steps)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-input"
    ]
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "```bash\n",
    "conda create -c conda-forge -n lsp 'python {REQUIRED_PYTHON}' 'jupyterlab={JUPYTERLAB_VERSION}' 'jupyterlab-lsp={JUPYTERLAB_LSP_VERSION}' 'jupyter-lsp-python={JUPYTER_LSP_VERSION}'\n",
    "conda activate lsp\n",
    "```\n",
    "\n",
    "Then run\n",
    "\n",
    "```bash\n",
    "jupyter lab\n",
    "```\n",
    "\n",
    "Your browser should open to your local server."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### docker (data science)\n",
    "\n",
    "This approach is based roughly on the\n",
    "[Jupyter docker-stacks documentation](https://github.com/jupyter/docker-stacks/tree/master/examples/docker-compose/notebook),\n",
    "which should be consulted for more about connecting volumes, passwords, and\n",
    "other advanced features:\n",
    "\n",
    "> Note: docker instructions were **not** updated for JupyterLab 3.0 and\n",
    "> extension 3.0. Please consider submitting a PR to fix it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### `Dockerfile`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-input"
    ]
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "\n",
    "```dockerfile\n",
    "# This already contains the python, r, julia, latex, and nodejs runtimes\n",
    "FROM jupyter/datascience-notebook@sha256:73a577b006b496e1a1c02f5be432f4aab969c456881c4789e0df77c89a0a60c2\n",
    "\n",
    "RUN conda install --quiet --yes --freeze-installed -c conda-forge \\\n",
    "    'python-language-server' \\\n",
    "    'jupyterlab={JUPYTERLAB_VERSION}' \\\n",
    "    'r-languageserver' \\\n",
    "    'texlab' \\\n",
    "    'chktex' \\\n",
    "    'jupyter-lsp={JUPYTER_LSP_VERSION}' \\\n",
    "  && jupyter labextension install --no-build \\\n",
    "    '@krassowski/jupyterlab-lsp@{JUPYTERLAB_LSP_VERSION}' \\\n",
    "  && jupyter lab build --dev-build=False --minimize=True \\\n",
    "  && conda clean --all -f -y \\\n",
    "  && rm -rf \\\n",
    "    $CONDA_DIR/share/jupyter/lab/staging \\\n",
    "    /home/$NB_USER/.cache/yarn \\\n",
    "  && fix-permissions $CONDA_DIR \\\n",
    "  && fix-permissions /home/$NB_USER\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### `docker-compose.yml`\n",
    "\n",
    "```yaml\n",
    "version: '2'\n",
    "\n",
    "services:\n",
    "  lsp-lab:\n",
    "    build: .\n",
    "    ports:\n",
    "      - '18888:8888'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Build and Start\n",
    "\n",
    "```bash\n",
    "docker-compose up\n",
    "```\n",
    "\n",
    "You should now be able to access `http://localhost:18888/lab`, using the `token`\n",
    "provided in the log."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Custom installation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Get a working JupyterLab environment\n",
    "\n",
    "Refer to the official\n",
    "[JupyterLab Installation Documentation](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html)\n",
    "for your installation approach.\n",
    "\n",
    "| pip            | conda            | pipenv | poetry | `*` |\n",
    "| -------------- | ---------------- | ------ | ------ | --- |\n",
    "| [lab][lab-pip] | [lab][lab-conda] | `*`    | `*`    | `*` |\n",
    "\n",
    "> `*` PRs welcome!\n",
    "\n",
    "Verify your lab works:\n",
    "\n",
    "```bash\n",
    "jupyter lab --version\n",
    "jupyter lab\n",
    "```\n",
    "\n",
    "[lab-conda]:\n",
    "  https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html#conda\n",
    "[lab-pip]:\n",
    "  https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html#pip"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "#### Install Jupyter[Lab] LSP\n",
    "\n",
    "##### conda"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-input"
    ]
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "```bash\n",
    "conda install jupyterlab-lsp={JUPYTERLAB_LSP_VERSION}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "##### pip"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-input"
    ]
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "```bash\n",
    "pip install jupyterlab-lsp=={JUPYTERLAB_LSP_VERSION}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Next step: Language Servers\n",
    "\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",
    "  servers to load"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}