[trivial] update docs with plugin info

doc/sphinx/src/building.rst

@@ -47,6 +47,7 @@ environment keeps Python packages isolated from the system installation:
    . riot_venv/bin/activate
    python -m pip install --upgrade pip
    python -m pip install numpy
+   python -m pip install "pybind11[global]"
 
 Additional Python packages, such as ``scipy`` and ``h5py``, may be installed
 in this virtual environment when needed by an input deck. Do not install them
@@ -79,6 +80,28 @@ The executable is built at ``build/src/riot``. To run a Cartesian example:
 
 The final command runs the example with four MPI ranks.
 
+.. _plugins-doc:
+
+Optional plugin physics
+-----------------------
+
+The optional CMake parameter ``PLUGINS_DIR`` enables additional plugin physics
+from a downstream source directory. Add it to the configuration command above:
+
+.. code-block:: bash
+
+   cmake -S . -B build -DPLUGINS_DIR=/absolute/path/to/plugins
+   cmake --build build --parallel 6
+
+The directory must contain a ``CMakeLists.txt``.
+
+Plugins are compiled into ``riot``. When ``PLUGINS_DIR`` is empty (the default),
+the build uses the no-op implementations in ``src/plugin_stubs``. Set
+``-DPLUGINS_DIR=`` to restore that behavior in an existing build directory.
+
+See :ref:`implementing-plugins` in the programmer's guide for the required
+interface functions and plugin CMake setup.
+
 Building in WSL
 ---------------
 
@@ -136,6 +159,11 @@ documentation.
    * - ``CMAKE_BUILD_TYPE``
      - ``RelWithDebInfo``
      - Build configuration. Common alternatives are ``Debug`` and ``Release``.
+   * - ``PLUGINS_DIR``
+     - empty
+     - Optional source directory containing a ``CMakeLists.txt`` to enable
+       additional plugin physics. See :ref:`plugins-doc` for the build setup
+       and a link to the implementation guide.
    * - ``RIOT_ENABLE_UNIT_TESTS``
      - ``OFF``
      - Build ``riot`` unit tests.

doc/sphinx/src/contributing.rst

@@ -72,7 +72,7 @@ AI-assisted coding
 generation, a disclaimer must be made in a comment in the relevant
 file. For example, you might add a comment like this one:
 
-..code-block:: c++
+.. code-block:: c++
 
   // This file was made in part with generative AI.
 
@@ -251,6 +251,13 @@ Be aware that the CI on the system runs sequentially and the number of
 concurrent jobs per user is limited. You may wish to cancel an old run
 if you no longer need the results and want your most recent run to finish.
 
+.. note::
+
+   After your PR is merged on github, the MR on the internal gitlab
+   does **not** need to be merged. The mirror will detect the merge
+   upstream and automatically close the MR. It *should* be safe to
+   merge by hand, but it is best practice not to do so.
+
 Setting git to automatically push to our CI system
 ````````````````````````````````````````````````````
 

doc/sphinx/src/programmer_guide.rst

@@ -49,6 +49,68 @@ style. Here we briefly discuss a few things one should be aware of.
   specifically need a single or double precision number, in which case
   you should specify the type as built into the language.
 
+.. _implementing-plugins:
+
+Implementing the plugin interface
+--------------------------------
+
+Plugins add downstream physics to ``riot`` through the
+``riot_plugins::Plugins`` interface. Select the plugin source directory
+with ``PLUGINS_DIR`` as described in :ref:`plugins-doc`.
+
+The directory must contain a ``CMakeLists.txt``. CMake adds this directory to the
+build after creating ``riotlib``; the plugin can add its implementation and
+physics sources to that target, for example:
+
+.. code-block:: cmake
+
+   target_sources(riotlib PRIVATE plugins.cpp)
+
+Include ``plugins.hpp`` in the plugin implementation and define all three
+members of ``riot_plugins::Plugins`` declared in ``src/plugins.hpp``. These
+definitions replace the built-in stubs; they are not virtual overrides or
+new overloads. Keep the signatures, including ``static`` and ``const``, as
+declared in the interface:
+
+.. code-block:: cpp
+
+   static void Initialize(ParameterInput *pin, Packages_t &pkgs);
+   void DriverParams(ParameterInput *pin, ApplicationInput *app_in, Mesh *pm);
+   TaskID AddSources(TaskList &tl, TaskID &dep, MeshData<Real> *mu0,
+                     Mesh *pmesh, const int partition_id, const Real dt) const;
+
+``Initialize``
+   Called during package setup, after the built-in physics packages and before
+   the problem package. Read plugin input from ``pin`` and register any plugin
+   packages, fields, and package parameters in ``pkgs``. This is a static member;
+   omit the ``static`` keyword in its out-of-class definition.
+
+``DriverParams``
+   Called from the ``RiotDriver`` constructor with the input, application, and
+   mesh objects. Initialize any plugin state needed by the driver, such as
+   physics flags or package references. The ``Plugins`` object provides a
+   ``parthenon::Params params`` member for storing this state.
+
+``AddSources``
+   Called when constructing source tasks for each mesh partition and integrator
+   stage. Add tasks to ``tl`` using ``dep`` as the incoming dependency. ``mu0`` is
+   the current stage's state, ``pmesh`` is the mesh, ``partition_id`` identifies
+   the partition, and ``dt`` is the timestep. Return a ``TaskID`` that depends on
+   all plugin source tasks, combining independent task IDs with ``|`` if needed.
+   The driver's state update waits on this returned dependency.
+
+   For source terms included in the stage update, register a ``"dudt"`` mesh-data
+   subset on the plugin package and populate it in the source tasks. The driver
+   gathers these subsets from all packages and adds their contributions with
+   the integrator's ``beta * dt`` weighting. See ``src/gravity/gravity.cpp`` for
+   an example of source-subset registration.
+
+All three definitions are required because selecting ``PLUGINS_DIR`` excludes
+the default stubs. Hooks that are not needed can use empty bodies for
+``Initialize`` and ``DriverParams``, and ``return dep;`` for ``AddSources``.
+The implementations in ``src/plugin_stubs/plugin_stubs.cpp`` provide a minimal
+starting point.
+
 Parthenon
 -----------