Contributing

Contributions to ANUGA are welcome — bug reports, documentation, and code. The full guide (forking, branching, and opening a pull request) is in the repository’s CONTRIBUTING.rst.

In brief:

  1. Fork and clone the repository, and set up a development install (see Install ANUGA for Developers).

  2. Create a feature branch and make your change. Add or update tests under the relevant anuga/*/tests/ directory, and keep the change focused.

  3. Run the test suite before submitting:

    pytest --pyargs anuga --run-fast     # quick check (~40 s)
pytest --pyargs anuga                # full suite (~1600 tests)

    and lint the files you touched:

    ruff check anuga/path/to/module.py

  4. Push to your fork and open a pull request against anuga-community/anuga_core, describing what the change does and why.

Bug reports and feature requests can be raised on the issue tracker.

Building the documentation

The documentation is built with Sphinx from docs/source. Read the Docs builds the main and develop branches automatically (https://anuga.readthedocs.io); to reproduce that build locally, install the same dependencies it uses and build the HTML:

pip install -r docs/requirements.txt
python -m sphinx -b html docs/source docs/_build/html

Aim for a warning-free build: Sphinx prints a bare build succeeded. when there are zero warnings, and build succeeded, N warnings. otherwise. Treat new warnings as errors to fix.

Note

Build in a clean environment created from docs/requirements.txt — not your everyday one. Packages you happen to have installed can hide warnings that Read the Docs then shows. Two that bit us:

  • a globally-installed IPython silently provides the ipython3 Pygments lexer the notebooks need, so its absence from docs/requirements.txt only surfaced on RTD;

  • building with -D nbsphinx_execute=never (or otherwise skipping the example notebooks) hides notebook-related warnings.

The class/method API pages are generated by autosummary + autodoc members, so a malformed docstring anywhere in the public API shows up as a build warning — another reason to keep the build green.