CONTRIBUTING.rst

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

• Follow PEP8 and you should be fine.
• The project uses Google Style Python docstrings
• The project uses black, flake8 and mypy to check for code style.

Development environment setup

• Clone the zhinst-toolkit repository

  $ git clone https://github.com/zhinst/zhinst-toolkit
  $ 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.

  Note

  Windows: Requires administration privileges.

  $ python .\scripts\zhinst_toolkit_symlink.py

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/generate_notebooks.py 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.

Structure

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.