Contributing

Python code style

black

We use black code formatter.

• Revision: 20.8b1.
• See configuration in pyproject.toml.

Install:

python -m pip install black

Run before each commit:

black .

License

We use addlicense license checker.

Install:

conda install go
export PATH=${PATH}:`go env GOPATH`/bin
go get -u github.com/google/addlicense

Run before each commit:

export PATH=${PATH}:`go env GOPATH`/bin
addlicense -l apache -c "Intel Corporation" numba_dpex/**/*.py numba_dpex/*.py setup.py

Security

Bandit

We use Bandit to find common security issues in Python code.

Install: pip install bandit

• Revision: 1.7.0

Run before each commit: bandit -r numba_dpex -lll

Documentation

Generating documentation

Install Sphinx and plugins:

pip install sphinx autodoc recommonmark sphinx-rtd-theme sphinxcontrib-apidoc

Generate HTML:

cd docs && make html

Run HTTP server:

cd docs/_build/html && python -m http.server 8000

Don't forget to change the version in docs/conf.py before generating.

release = "<VERSION>"

Generated documentation will be in docs/_build/html.

Documentation common issues

1. Use :language: shell-session for GDB shell sessions:

.. literalinclude:: <...>
  :language: shell-session

2. Use :language: bash for commands which could be inserted in shell or script:

.. code-block:: bash
    export IGC_ShaderDumpEnable=1

3. Use :lineno-match: if line numbers matter and example file contains license header:

.. literalinclude:: <...>
    :linenos:
    :lineno-match:

Uploading to GitHub Pages

Documentation for GitHub Pages is placed in following branch gh-pages.

Folders:

• dev folder contains current documentation for default branch.
• 0.12.0 folder and other similar folders contain documentation for releases.
• latest folder is a link to the latest release folder.

Copy generated documentation into corresponding folder and create pull request to gh-pages branch.

Code Coverage

Implement python file coverage using coverage and pytest-cov packages.

Using coverage

Install Coverage:

pip install coverage

Run Coverage:

coverage run -m pytest

Show report:

coverage report

• For each module executed, the report shows the count of executable statements, the number of those statements missed, and the resulting coverage, expressed as a percentage.

The -m flag also shows the line numbers of missing statements:

coverage report -m

Produce annotated HTML listings with coverage results:

coverage html

Produce XML with coverage for VSCode plugin:

coverage xml

• The htmlcov folder will appear in the root folder of the project. It contains reports on python file coverage in html format.

Erase previously collected coverage data:

coverage erase

Using pytest-cov

This plugin provides a clean minimal set of command line options that are added to pytest.

You must have coverage package installed to use pytest-cov.

Install pytest-cov:

conda install pytest-cov

Run pytest-cov:

pytest --cov=numba_dpex

The complete list of command line options is:

• --cov=PATH

Measure coverage for filesystem path. (multi-allowed)

• --cov-report=type

Type of report to generate: term(the terminal report without line numbers (default)), term-missing(the terminal report with line numbers), annotate, html, xml (multi-allowed).