This notebook is part of the nbsphinx
documentation: https://nbsphinx.readthedocs.io/.
Note that some packages may be out of date.
You can always get the newest nbsphinx
release from PyPI (using pip
).
If you want to try the latest development version, have a look at the section Contributing.
If you are using the conda
package manager (e.g. with Anaconda for Linux/macOS/Windows), you can install nbsphinx
from the conda-forge channel:
conda install -c conda-forge nbsphinx
If you are using Linux, there are packages available for many distributions.
On any platform, you can also install nbsphinx
with pip
, Python's own package manager:
python3 -m pip install nbsphinx --user
If you want to install it system-wide for all users (assuming you have the necessary rights), just drop the --user
flag.
To upgrade an existing nbsphinx
installation to the newest release, use the --upgrade
flag:
python3 -m pip install nbsphinx --upgrade --user
If you suddenly change your mind, you can un-install it with:
python3 -m pip uninstall nbsphinx
Depending on your Python installation, you may have to use python
instead of python3
.
Some of the aforementioned packages will install some of these prerequisites automatically, some of the things may be already installed on your computer anyway.
Of course you'll need Python, because both Sphinx and nbsphinx
are implemented in Python.
There are many ways to get Python.
If you don't know which one is best for you, you can try Anaconda.
You'll need Sphinx as well, because nbsphinx
is just a Sphinx extension and doesn't do anything on its own.
If you use conda
, you can get Sphinx from the conda-forge channel:
conda install -c conda-forge sphinx
Alternatively, you can install it with pip
(see below):
python3 -m pip install Sphinx --user
Recent versions of Python already come with pip
pre-installed.
If you don't have it, you can install it manually.
The stand-alone program pandoc 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:
conda install -c conda-forge pandoc
If that doesn't work out for you, have a look at pandoc
's installation instructions.
To get proper syntax highlighting in code cells, you'll need an appropriate Pygments lexer.
This of course depends on the programming language of your Jupyter notebooks (more specifically, the pygments_lexer
metadata of your notebooks).
For example, if you use Python in your notebooks, you'll have to have the IPython
package installed, e.g. with
conda install -c conda-forge ipython
or
python3 -m pip install IPython --user
If you want to execute your notebooks during the Sphinx build process (see Controlling Notebook Execution), you need an appropriate Jupyter kernel installed.
For example, if you use Python, you should install the ipykernel
package, e.g. with
conda install -c conda-forge ipykernel
or
python3 -m pip install ipykernel --user
If you created your notebooks yourself with Jupyter, it's very likely that you have the right kernel installed already.