docs/Installation.ipynb

{
 "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": {},
   "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": [
    "### 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",
    "Verify your lab works:\n",
    "\n",
    "```bash\n",
    "jupyter lab --version\n",
    "jupyter lab\n",
    "```"
   ]
  },
  {
   "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 (ipykernel)",
   "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.11.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}