Contributing#

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.

Code Improvements#

All development for this library happens on GitHub here. We recommend you work with a Conda environment (or an alternative virtual environment like venv).

The below instructions also use Mamba which is a very fast implementation of conda.

git clone <your fork>
cd pymmcore-plus
mamba create -n pymm-dev -c conda-forge python
conda actiavte pymm-dev
pip install -e ".[testing, docs]"
pip install pre-commit
pre-commit install

The -e . flag installs the pymmcore_plus folder in “editable” mode and [testing, docs] installs the optional dependencies you need for developing pymmcore_plus.

Working with Git#

pymmcore-plus is developed using the github flow. 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.

Documentation#

Our documentation on Read the Docs (pymmcore-plus.rtfd.io) is built with Sphinx from the notebooks in the docs folder. It contains both Markdown files and Jupyter notebooks.

Examples are best written as ipynb or an md file. 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.md 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 docs folder:

make html

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

make watch

from inside the docs folder

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!