Ways to contribute#

  • Opening a new ticket to Issues or by commenting on existing one with new solutions or suggestions

  • By improving the project documentation.

  • By improving and adding new project examples.

  • By contributing code; bug fixes, new features and so on.

Code contributions#

Development environment setup#

  • Clone the zhinst-toolkit repository

    $ git clone
    $ cd zhinst-toolkit
  • Create a Python virtual environment

  • Install the dependencies

    $ pip install -r requirements.txt
  • Add zhinst-toolkit to zhinst package namespace by running the script to create a symbolic link between development files and zhinst-package.


    Windows: Requires administration privileges.

    $ python .\scripts\

Running the tests#

Running all tests#

$ pytest

Running lint test#

$ tox -e lint

Running typing tests#

$ tox -e typing

Running code format check#

$ tox -e black

Running coverage#

$ pip install coverage
$ coverage run -m pytest
$ coverage html

The report can be seen in your browser by opening htmlcov/index.html.

Building the examples#

The examples are stored as Markdown files. If you wish to turn the local examples/*.md files into Jupyter Notebooks by using the following script:

$ python scripts/ local

Building the documentation#

Zhinst-toolkit uses Sphinx to build the package documentation.

  • Install the package in editable mode

    $ pip install -e .

Change to docs directory

$ cd docs
  • Install the docs dependencies

    $ pip install -r docs/requirements.txt
  • Build the HTML documentation along with examples with Sphinx

    $ make html [local | remote]

The generated documentation can be seen in your browser by opening docs/html/index.html.

Pull requests#

Use Github pull requests to contribute your code.

Use an existing Pull request template and follow it.

Writing examples#

Examples are a good way to demonstrate on how the library is used to execute various experiments and measurements. Examples using zhinst Toolkit are welcome.

File format#

The examples are written by using Jupyter Notebooks, but version controlled as Markdown files.

The ready made example Notebooks can be translated to a Markdown file by using Jupytext.


Please see the existing examples in /examples and try to keep the same structure. Including the output of Notebook cells is highly encouraged.

Adding to documentation#

Version controlled Markdown files are translated to Notebooks in CI and then to HTML for display.

To include the example in HTML documentation, create an NB link in docs.