Development
===========

The repo-local ``.venv`` is the preferred environment for contributors working
on tests or documentation:

.. code-block:: sh

   tests/prepare.sh

The preparation script installs the package in editable mode with both test and
documentation extras:

.. code-block:: text

   .[test,docs]

Run Tests
---------

Run the modern pytest suite:

.. code-block:: sh

   .venv/bin/python -m pytest --ignore=tests/legacy --ignore=tests/support tests

The legacy harness remains available separately and is intentionally not part of
the default pytest run.

Build Docs
----------

Build HTML documentation:

.. code-block:: sh

   .venv/bin/sphinx-build -b html docs docs/_build/html

The same command is wrapped by the Sphinx ``Makefile``:

.. code-block:: sh

   make -C docs html

VS Code
-------

The repository includes ``.vscode/extensions.json`` with recommended
extensions, including Esbonio for Sphinx language-server support. The workspace
settings point Python tooling and Esbonio at the repo-local ``.venv``.