Ways to contribute#
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.
Windows: Requires administration privileges.
$ python .\scripts\zhinst_toolkit_symlink.py
Running the tests#
Running all tests#
Running lint test#
$ tox -e lint
Running typing tests#
$ tox -e typing
Running code format check#
$ tox -e black
$ 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.
Use Github pull requests to contribute your code.
Use an existing Pull request template and follow it.
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.
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.