Developer Guide
---------------

This section covers the day-to-day development workflow for ``rgpot``.

Environment Setup
~~~~~~~~~~~~~~~~~

All development is managed through `pixi <https://pixi.sh>`_. Install it first, then:

.. code:: bash

    pixi install          # default environment (build + test)
    pixi shell            # activate the environment

Available environments:

.. table::

    +-------------+-------------------------------------------------+
    | Environment | Purpose                                         |
    +=============+=================================================+
    | *(default)* | C/C++ build tools, Rust toolchain, linting      |
    +-------------+-------------------------------------------------+
    | ``rpctest`` | RPC integration tests (pycapnp, numpy)          |
    +-------------+-------------------------------------------------+
    | ``devbld``  | Full dev build (RPC + cache features)           |
    +-------------+-------------------------------------------------+
    | ``docs``    | Documentation build (Sphinx, Doxygen, doxyrest) |
    +-------------+-------------------------------------------------+
    | ``cigen``   | CI workflow generation (Nickel)                 |
    +-------------+-------------------------------------------------+

Common Tasks
~~~~~~~~~~~~

All tasks are invoked via ``pixi r <task>``:

.. table::

    +---------------------+--------------------------------------------------------------+
    | Task                | Description                                                  |
    +=====================+==============================================================+
    | ``rust-test``       | Run Rust unit tests with nextest                             |
    +---------------------+--------------------------------------------------------------+
    | ``rust-test-all``   | Run Rust tests with all features enabled                     |
    +---------------------+--------------------------------------------------------------+
    | ``gen-header``      | Regenerate ``include/rgpot.h`` from Rust source via cbindgen |
    +---------------------+--------------------------------------------------------------+
    | ``gen-gha``         | Regenerate GitHub Actions workflow from Nickel template      |
    +---------------------+--------------------------------------------------------------+
    | ``towncrier-draft`` | Preview release notes (dry run)                              |
    +---------------------+--------------------------------------------------------------+
    | ``towncrier-build`` | Write release notes into ``CHANGELOG.md``                    |
    +---------------------+--------------------------------------------------------------+
    | ``docbld``          | Build full documentation (org export + Doxygen + Sphinx)     |
    +---------------------+--------------------------------------------------------------+
    | ``docdel``          | Clean all generated documentation artifacts                  |
    +---------------------+--------------------------------------------------------------+
    | ``gen-readme``      | Export ``rgpot-core/README.org`` to ``README.md`` (docs env) |
    +---------------------+--------------------------------------------------------------+

Regenerating the C Header
~~~~~~~~~~~~~~~~~~~~~~~~~

The C header ``rgpot-core/include/rgpot.h`` is auto-generated by ``cbindgen`` from
the Rust source. It is committed to the repository so C/C++ consumers always
have a working copy. After changing the public Rust API:

.. code:: bash

    pixi r gen-header
    git diff rgpot-core/include/rgpot.h  # review changes

The ``gen-header`` feature is excluded from default builds and from ``cargo publish`` to avoid modifying the source tree during packaging.

Building Documentation
~~~~~~~~~~~~~~~~~~~~~~

Documentation is built with Sphinx and served at `rgpot.rgoswami.me <https://rgpot.rgoswami.me>`_. It combines:

- **Org-mode pages** (this guide, architecture, changelog) exported to RST

- **C++ API reference** generated by Doxygen + doxyrest

- **Rust API reference** generated by ``sphinxcontrib-rust``

To build locally:

.. code:: bash

    pixi r -e docs docbld
    # Open docs/build/index.html

To clean generated artifacts:

.. code:: bash

    pixi r -e docs docdel

Pre-commit Hooks
~~~~~~~~~~~~~~~~

.. code:: bash

    uvx pre-commit run --all-files

CI runs these automatically on every PR via ``pipx run prek``.

  .. toctree::
     :maxdepth: 2
     :caption: Details

     testing
     release
     faq