mirror of
https://github.com/wassname/jupyter_contrib_nbextensions.git
synced 2026-06-27 16:10:24 +08:00
Josh Barnes
62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
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.
|