Skip to content

Files

Latest commit

Mar 27, 2018
7aa0192 · Mar 27, 2018

History

History
This branch is 164 commits behind ipython-contrib/jupyter_contrib_nbextensions:master.

Documenting jupyter_contrib_nbextensions

Documentation for jupyter_contrib_nbextensions is hosted on ReadTheDocs.

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 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:

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.