doc/installation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installation\n",
    "\n",
    "Note that some packages may be out of date.\n",
    "You can always get the newest `nbsphinx` release from [PyPI](https://pypi.org/project/nbsphinx) (using `pip`).\n",
    "If you want to try the latest development version, have a look at the section [Contributing](contributing.rst).\n",
    "\n",
    "## `nbsphinx` Packages\n",
    "\n",
    "[![Anaconda Badge](https://anaconda.org/conda-forge/nbsphinx/badges/version.svg)](https://anaconda.org/conda-forge/nbsphinx)\n",
    "\n",
    "If you are using the `conda` package manager\n",
    "(e.g. with\n",
    "[Miniforge](https://github.com/conda-forge/miniforge),\n",
    "[Miniconda](https://docs.conda.io/en/latest/miniconda.html) or\n",
    "[Anaconda](https://www.anaconda.com/download#downloads)),\n",
    "you can install `nbsphinx` from the [conda-forge](https://conda-forge.org/) channel:\n",
    "\n",
    "    conda install -c conda-forge nbsphinx\n",
    "\n",
    "[![PyPI version](https://badge.fury.io/py/nbsphinx.png)](https://pypi.org/project/nbsphinx)\n",
    "\n",
    "You can of course also install `nbsphinx` with `pip`, Python's own package manager:\n",
    "\n",
    "    python3 -m pip install nbsphinx\n",
    "\n",
    "Depending on your Python installation,\n",
    "you may have to use `python` instead of `python3`.\n",
    "If you have installed the module already,\n",
    "you can use the `--upgrade` flag to get the newest release.\n",
    "\n",
    "There are more packages available.\n",
    "For an overview, see\n",
    "[repology](https://repology.org/project/python:nbsphinx/versions)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `nbsphinx` Prerequisites\n",
    "\n",
    "Some of the aforementioned packages will install some of these prerequisites automatically, some of the things may be already installed on your computer anyway.\n",
    "\n",
    "### Python\n",
    "\n",
    "Of course you'll need Python, because both Sphinx and `nbsphinx` are implemented in Python.\n",
    "There are many ways to get Python.\n",
    "If you don't know which one is best for you, you can try [Miniforge/Mambaforge](https://github.com/conda-forge/miniforge).\n",
    "\n",
    "### Sphinx\n",
    "\n",
    "You'll need [Sphinx](https://www.sphinx-doc.org/) as well, because `nbsphinx` is just a Sphinx extension and doesn't do anything on its own.\n",
    "\n",
    "If you use `conda`, you can get [Sphinx from the conda-forge channel](https://anaconda.org/conda-forge/sphinx):\n",
    "\n",
    "    conda install -c conda-forge sphinx\n",
    "\n",
    "Alternatively, you can install it with `pip` (see below):\n",
    "\n",
    "    python3 -m pip install Sphinx\n",
    "\n",
    "### pip\n",
    "\n",
    "Recent versions of Python already come with `pip` pre-installed.\n",
    "If you don't have it, you can [install it manually](https://pip.pypa.io/en/latest/installing/).\n",
    "\n",
    "### pandoc\n",
    "\n",
    "The stand-alone program [pandoc](https://pandoc.org/) is used to convert Markdown content to something Sphinx can understand. You have to install this program separately, ideally with your package manager. If you are using `conda`, you can install [pandoc from the conda-forge channel](https://anaconda.org/conda-forge/pandoc):\n",
    "\n",
    "    conda install -c conda-forge pandoc\n",
    "\n",
    "If that doesn't work out for you, have a look at `pandoc`'s [installation instructions](https://pandoc.org/installing.html).\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "The use of `pandoc` in `nbsphinx` is temporary, but will likely stay that way for a long time, see [issue #36](https://github.com/spatialaudio/nbsphinx/issues/36).\n",
    "\n",
    "</div>\n",
    "\n",
    "### Pygments Lexer for Syntax Highlighting\n",
    "\n",
    "To get proper syntax highlighting in code cells, you'll need an appropriate *Pygments lexer*.\n",
    "This of course depends on the programming language of your Jupyter notebooks (more specifically, the `pygments_lexer` metadata of your notebooks).\n",
    "\n",
    "For example, if you use Python in your notebooks, you'll have to have the `IPython` package installed, e.g. with\n",
    "\n",
    "    conda install -c conda-forge ipython\n",
    "\n",
    "or\n",
    "\n",
    "    python3 -m pip install IPython\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "If you are using Anaconda with the default channel and syntax highlighting in code cells doesn't seem to work,\n",
    "you can try to install IPython from the `conda-forge` channel or directly with `pip`, or as a work-around,\n",
    "add `'IPython.sphinxext.ipython_console_highlighting'` to `extensions` in your `conf.py`.\n",
    "\n",
    "For details, see [Anaconda issue #1430](https://github.com/ContinuumIO/anaconda-issues/issues/1430) and\n",
    "[nbsphinx issue #24](https://github.com/spatialaudio/nbsphinx/issues/24).\n",
    "\n",
    "</div>\n",
    "\n",
    "### Jupyter Kernel\n",
    "\n",
    "If you want to execute your notebooks during the Sphinx build process (see [Controlling Notebook Execution](executing-notebooks.ipynb)), you need an appropriate [Jupyter kernel](https://jupyter.readthedocs.io/en/latest/projects/kernels.html) installed.\n",
    "\n",
    "For example, if you use Python, you should install the `ipykernel` package, e.g. with\n",
    "\n",
    "    conda install -c conda-forge ipykernel\n",
    "\n",
    "or\n",
    "\n",
    "    python3 -m pip install ipykernel\n",
    "\n",
    "If you created your notebooks yourself with Jupyter, it's very likely that you have the right kernel installed already.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "If your [automatic builds](usage.ipynb#Automatic-Creation-of-HTML-and-PDF-output-on-readthedocs.org) on https://readthedocs.org are failing due to an error like the one below, add `ipykernel` to `docs/requirements.txt` or `doc/environment.yml` to resolve.\n",
    "\n",
    "```\n",
    "jupyter_client.kernelspec.nosuchkernel: no such kernel named python3\n",
    "```\n",
    "\n",
    "</div>\n"
   ]
  }
 ],
 "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}