{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "import sys\n",
    "\n",
    "from format_markdown import markdown\n",
    "\n",
    "sys.path.insert(0, \"..\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "### Please Read This First\n",
    "\n",
    "Delivering LSP features to your JupyterLab **requires** three pieces:\n",
    "\n",
    "#### `jupyter-lsp`\n",
    "\n",
    "- runs in your `jupyter_server` web 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}`\n",
    "\n",
    "#### `jupyterlab-lsp`\n",
    "\n",
    "- runs in your browser, as an extension to JupyterLab\n",
    "- to install it, you need:\n",
    "  - `jupyterlab {REQUIRED_JUPYTERLAB}`\n",
    "\n",
    "#### Language Servers\n",
    "\n",
    "- run on your server\n",
    "  - probably in another language runtime than python\n",
    "- some can be automatically [detected](./Language%20Servers.ipynb) if installed\n",
    "- others also need to be [configured](./Configuring.ipynb#language_servers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Fast Paths\n",
    "\n",
    "Here are two approaches based on Jupyter documentation. If these do not meet\n",
    "your needs, try [The Harder Way](#The-Harder-Way)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "#### conda (minimal python)\n",
    "\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",
    "# jupyter-lsp-python includes both the server extension (jupyter-lsp) and pyls third-party server (python-language-server)\n",
    "# if you swap it with another pre-made bundle, jupyter-lsp-r, you will get the server extension and r-languageserver;\n",
    "# alternatively, manually install a language server of your choice (see the table below).\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": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "##### `Dockerfile`\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": [
    "### The Harder Way"
   ]
  },
  {
   "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": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "%%markdown\n",
    "#### Install Jupyter[Lab] LSP\n",
    "\n",
    "##### conda\n",
    "\n",
    "```bash\n",
    "conda install jupyterlab-lsp={JUPYTERLAB_LSP_VERSION}\n",
    "```\n",
    "\n",
    "##### pip\n",
    "\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
}