Development Guidelines

Todo

This whole section needs to be written. The general gist is:

• We use PDM at the package manager/virtual env for isolation.

  • pdm test for Pytest, pdm doc for Sphinx, etc.

• We also use PDM’s build backend as the build system, but this can be interfaced to via pip.

• We use pytest’s Pytester plugin to test our plugin.

  • See [tool.pytest.ini_options] for pytest config required for tests to function properly (including doctests).

  • Doctests that are not intended to be invoked via pytest are nominally run through pytest-sphinx.

    • pdm doc-test, which calls sphinx-build -b doctest, is provided as a fallback in case pytest-sphinx misses a doctest.

  • AFAICT, it is not possible to invoke Pytester through doctest, so all Python code in docs and intended to be invoked via pytest is duplicated in test_inject.py, and run as part of the main pytest suite (test_inject_sim_args).

• Linting is done with a combination of ruff, pydoclint, and transitively, flake8.

  • flake8 usage is minimized to pydoclint and lints that are unstable in ruff. See .flake8 file (flake8 doesn’t support pyproject.toml).

  • Eventually, this should go down to only ruff, when the pydoclint functionality and extra flake8 lints are stabilized. See [tool.ruff] section in pyproject.toml and compare to .flake8; lint rule overlap should be minimized.

• Docs are written in Markdown using myst when possible.