Documenting jupyter_contrib_nbextensions
========================================

Documentation for `jupyter_contrib_nbextensions`
is [hosted on ReadTheDocs](https://jupyter_contrib_nbextensions.readthedocs.org/en/latest/).


Building the documentation locally
----------------------------------

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](../tox.ini) for details.

From the repository root:

1. Install tox:

    $ pip install tox

2. Run the tox environment:

    $ tox -e docs

3. 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`.


Developing Documentation
------------------------

Helpful files and directories:

 * `source` directory - source files for documentation.
 * [source/conf.py](source/conf.py) - Sphinx build configuration file.
 * [source/autogen_scripts/autogen_nbextensions_list.py](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](https://github.com/rtfd/recommonmark).
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.