Thanks for thinking of a way to help improve this library! Remember that contributions come in all shapes and sizes beyond writing bug fixes. Contributing to documentation, opening new issues for bugs, asking for clarification on things you find unclear, and requesting new features, are all super valuable contributions.
All development for this library happens on GitHub here. We recommend you work with a Conda environment (or an alternative virtual environment like
The below instructions use Mamba which is a very fast implementation of
git clone <your fork> cd ipympl mamba env create --file dev-environment.yml conda activate ipympl-dev pre-commit install
Install the Python Packge
pip install -e .
When developing your extensions, you need to manually enable your extensions with the notebook / lab frontend. For lab, this is done by the command:
jupyter labextension develop --overwrite . yarn run build
For classic notebook, you need to run:
jupyter nbextension install --py --symlink --sys-prefix --overwrite ipympl jupyter nbextension enable --py --sys-prefix ipympl
How to see your changes#
If you use JupyterLab to develop then you can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension’s source and automatically rebuild the widget.
# Watch the source directory in one terminal, automatically rebuilding when needed yarn run watch # Run JupyterLab in another terminal jupyter lab
After a change wait for the build to finish and then refresh your browser and the changes should take effect.
If you make a change to the python code then you will need to restart the notebook kernel to have it take effect.
Our documentation is built with Sphinx from the notebooks in the
docs folder. It contains both Markdown files and Jupyter notebooks.
Examples are best written as Jupyter notebooks. To write a new example, create in a notebook in the
docs/examples directory and list its path under one of the
toctrees in the
index.ipynb file. When the docs are generated, they will be rendered as static html pages by myst-nb.
If you have installed all developer dependencies (see above), you can rebuild the docs with the following
make command run from inside the
Then you can open the
_build/index.html file in your browser you should now be able to see the rendered documentation.
Alternatively, you can use sphinx-autobuild to continuously watch source files for changes and rebuild the documentation for you. Sphinx-autobuild will be installed automatically in the dev environment you created earlier so all you need to do is run
from inside the
In a few seconds your web browser should open up the documentation. Now whenever you save a file the documentation will automatically regenerate and the webpage will refresh for you!
Working with Git#
Using Git/GitHub can confusing (https://xkcd.com/1597), so if you’re new to Git, you may find it helpful to use a program like GitHub Desktop and to follow a guide.
Also feel free to ask for help/advice on the relevant GitHub issue.
Getting Help contributing#
Feel free to ask questions about how to contribute on any Github Issue. You can also ask shorter questions on the gitter chatroom.