Documentation for jupyter_contrib_nbextensions
is hosted on ReadTheDocs.
The easiest way to build the docs locally is to use the provided tox
environment, docs
. Essentially this just installs the correct dependencies
into a vitrualenv, and calls sphinx-build
with the correct arguments.
See the repo's tox.ini for details.
From the repository root:
-
Install tox:
$ pip install tox
-
Run the tox environment:
$ tox -e docs
-
Display the documentation locally by navigating to
build/html/index.html
in your browser.Or alternatively you may run a local server to display the docs. In Python 3:
$ python -m http.server 8000
Then, in your browser, go to
http://localhost:8000
.
Helpful files and directories:
source
directory - source files for documentation.- source/conf.py - Sphinx build configuration file.
- source/autogen_scripts/autogen_nbextensions_list.py - Generates an rst file listing each of the provided nbextensions readmes.
The readme files for each nbextension are incorporated into the documentation by using the recommonmark parser. This is configured in the Sphinx configuration file (see above), but has some limitations compared to the markdown spec routinely used on, for example, GitHub, most notably things like:
- no table support
- no auto-linking of urls
In order to get the nbextensions' readmes to build in sphinx, they must be
inside the docs source_dir
.
As a result, we install the nbextensions into the docs/source
directory as
part of the build process, in autogen_nbextensions_list.py
. The install is
performed using symlinks on non-windows platforms, to minimize the amount of
writing needed. Symlinks aren't supported on Windows without admin rights, so
we have to use the regular install process which copies the files.