dev_docs.md

Develop and Build Documentation

To build the documentation you'll need Sphinx and a few other packages.

Setup documentation environment

Use mamba or conda (recommended)

First create a conda environment named ipywidgets_docs to install all the necessary packages:

# create the environment
mamba env update --file docs/environment.yml

Then, activate the environment.

# activate the environment
conda activate ipywidgets_docs   # Linux and OS X
activate ipywidgets_docs         # Windows

Use pip

Alternatively, it is also possible to create a virtual environment and activate it with the following commands:

# create the environment
python -m venv .

# activate the environment
source bin/activate

In the environment, install the packages:

python -m pip install -r docs/requirements.txt

Building the documentation site requires a working `nodejs` installation, which
can be installed with your package manager of choice, or directly from the
[NodeJS website](https://nodejs.org).

Build the documentation

Once you have installed the required packages, you can build the docs with:

cd docs/source
sphinx-build -T -E -b html -d ../build/doctrees -D language=en . ../build/html

After that, the generated HTML files will be available at build/html/index.html. You may view the docs in your browser by entering the following in the terminal: open build/html/index.html. Alternatively, you can start the built-in Python web server:

cd docs/build/html
python3 -m http.server -b 127.0,0.1

... and navigate to http://localhost:8000/.

You should also have a look at the Project Jupyter Documentation Guide.

Watch the documentation

It is also possible to launch a web server which watches the sources and automatically rebuilds:

cd docs/source
sphinx-autobuild -T -E -b html -d ../build/doctrees -D language=en . ../build/html

... and navigate to http://localhost:8000/.

Cleaning notebook output for docs

When using notebook source files to generate documentation, it's good practice to strip notebook output and metadata with nbstripout before committing the notebook. For example, the following command will strip all output from a notebook:

nbstripout "docs/source/examples/Widget List.ipynb"