Contributing

Setting up

git clone https://github.com/StatisticalRL/statrl.git
cd statrl
pip install -e ".[test,lint]"
pip install -r docs/requirements.txt

Checks

The same checks run in CI. Run them before opening a pull request:

pytest                                              # unit tests
ruff check src && mypy                              # lint and types
sphinx-build -b html -W --keep-going docs/source docs/_build/html
sphinx-build -b doctest docs/source docs/_build/doctest

Adding a setting

A setting is a folder under src/statrl/settings/ with a fixed layout, which statrl.settings.validator checks:

mysetting/
  agent.py            # base agent class for the setting
  environment.py      # environment class
  interaction.py      # Interaction subclass
  _test.py            # smoke script
  agents/             # concrete algorithms
  envs/               # concrete instances, plus environments.yaml
  renderers/          # optional display
  wrappers/           # optional adapters to other settings

python -m statrl.settings.validator

Documentation

Docstrings are numpydoc style, rendered through sphinx.ext.napoleon. Every public object must have a docstring and be listed in docs/source/api/.

Follow the conventions the existing docstrings use:

• Document constructor parameters on the class, not on __init__.

• Give every algorithm a References section citing its paper, and add the entry to Bibliography.

• Use See Also to link variants and counterparts; it is what makes the reference navigable.

• Put runnable Examples in docstrings where the object can be exercised in a couple of lines. They run under pytest --doctest-modules in CI.

When adding a setting, add both an api/<setting>.rst and a user_guide/<setting>.rst, and list them in the two index.rst files. An API page that no user_guide page explains is a reference nobody can enter.