{ "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 (e.g. with [Anaconda](https://www.anaconda.com/products/individual#Downloads) for Linux/macOS/Windows), 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", "[venv]: https://docs.python.org/3/tutorial/venv.html" ] }, { "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 [Anaconda](https://www.anaconda.com/products/individual#Downloads).\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", "
\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", "
\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", "
\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", "
\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", "
\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", "
\n" ] } ], "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.8.5" } }, "nbformat": 4, "nbformat_minor": 4 }