dev_docs.md

Building the Documentation

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

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

# create the environment
conda create -n ipywidgets_docs -c conda-forge python pip

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

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

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

cd docs
make clean
make html

After that, the generated HTML files will be available at build/html/index.html. You may view the docs in your browser.

Windows users can find make.bat in the docs folder.

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

Cleaning notebooks for docs

Notebook output and metadata should be stripped with nbstripoutput before commiting. For example:

nbstripoutput docs/source/examples/Widget\ List.ipynb