If you have not already, please review CONTRIBUTING.md for more complete information on expectations for contributions.
Please note that only a subset of Dioptra's components work natively on Windows. You can develop for the frontend or REST API natively on Windows, and Windows-specific instructions for setting up the environment are available in the dev-kb/local-setup/MANUAL.md file. However, if you need to run all of Dioptra's components locally, you must install and use WSL2.
See the Local Developer Set-up knowledge base article for instructions.
This project uses Sphinx to generate the documentation published at https://pages.nist.gov/dioptra and uses tox to run it.
If you haven't done so yet, install tox as a uv tool:
uv tool install --python 3.11 tox --with tox-uv
To build the documentation locally, run:
uvx tox run -e web-compile,docs
This project uses ruff to lint and format code and uses tox to run it.
If you haven't done so yet, install tox as a uv tool:
uv tool install --python 3.11 tox --with tox-uv
To run the code linter, use:
# Run this to lint (but not fix) your code
uvx tox run -e lint
# Run this to lint your code and fix it where possible (includes import sorting)
uvx tox run -e lint -- --fix src/dioptra
To run the code formatter, use:
# Run this to check (but not fix) your code formatting
uvx tox run -e format
# Run this to fix your code formatting automatically
uvx tox run -e format -- src/dioptra
At a minimum, you should run this before opening a merge request on your branch:
uvx tox run -e lint -- --select I --fix src/dioptra
uvx tox run -e format -- src/dioptra
This project uses mypy to type check code and uses tox to run it.
If you haven't done so yet, install tox as a uv tool:
uv tool install --python 3.11 tox --with tox-uv
To run the type checker, use:
uvx tox run -e mypy
This project has a commit style guide that is enforced using the gitlint tool and uses tox to run it.
If you haven't done so yet, install tox as a uv tool:
uv tool install --python 3.11 tox --with tox-uv
Developers are expected to run gitlint and validate their commit message before opening a Pull Request.
After committing your contribution, run:
uvx tox run -e gitlint
This project stores its pytest-based unit tests in the tests/ folder and uses tox to run it.
If you haven't done so yet, install tox as a uv tool:
uv tool install --python 3.11 tox --with tox-uv
Developers are expected to create new unit tests to validate any new features or behavior that they contribute and to verify that all unit tests pass before opening a Pull Request. To run the unit tests:
uvx tox run -e pytest -- tests/unit
uvx tox run -e pytest-cookiecutter
uvx tox run -e pytest-extra
NOTE: This command will not work in a Windows environment.
Run the following to clear away the project's temporary files, which includes the sentinel dotfiles that are created in build/ when using make:
make clean
The uv.lock file is generated by uv as a standardized lockfile that specifies exact versions of Python dependencies, ensuring reproducible and consistent builds across different environments. To keep dependencies up-to-date and apply important fixes or improvements, a maintainer should periodically upgrade the lockfile by running:
uv lock --upgrade