Development

The tox.toml and Makefile provide an overview of the CI processing.

Makefile targets:

  • quick: Uses the quick environment in tox.

  • test: the full test suite, including static analysis.

  • docs: Creates the documentation.

  • docs-coverage: a report of how many modules, classes, methods, and functions have documentation.

  • apidoc_gen: re-generates an apidoc.rst. Useful after significant revisions or extensions.

Tox environments.

  • default, used by tox run is a full test suite, and static analysis.

  • quick runs the tests in the tests directory.

  • demo runs the tests in the demo directory.

  • docs runs doctest on the examples in the documentation.

Testing

There are three “tiers” of testing for Stingray Reader.

  • Unit testing.

    • Some tests use pytest. This should have 100% code coverage.

    • Additional tests use doctest. These are examples from code and documentation that are also validated.

  • Integration testing. All of the sample files are processed through a test case to be sure they can be read.

  • Acceptance testing. The demo directory contains applications which serve as acceptance test cases.

Static Analysis

Additionally, ruff and pyright are used to be sure the code has no obvious flaws and the type hints are correct and consistent.

Documentation

Sphinx is used.

Note that diagrams are created with plantUML. This relies on Java. Both the Makefile and the config.py references to the required JAR file.

Makefile:

curl -LSf https://github.com/plantuml/plantuml/releases/download/v1.2024.7/plantuml-1.2024.7.jar -o .plantuml/plantuml-1.2024.7.jar

docs/source/config.py:

_plantuml_path = Path.cwd().parent.parent / ".plantuml" / "plantuml-1.2024.7.jar"

Yes. Both of these pin a specific version number. It changes rarely.