.. _contributing:

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
<https://github.com/anuga-community/anuga_core/blob/main/CONTRIBUTING.rst>`_.

In brief:

#. Fork and clone the
   `repository <https://github.com/anuga-community/anuga_core>`_, and set up a
   development install (see :doc:`../installation/install_anuga_developers`).

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

#. Run the test suite before submitting:

   .. code-block:: bash

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

   and lint the files you touched:

   .. code-block:: bash

      ruff check anuga/path/to/module.py

#. 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 <https://github.com/anuga-community/anuga_core/issues>`_.


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:

.. code-block:: bash

   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.