.. _interactive-examples:

####################
Interactive examples
####################

Interactive examples are a good fit for |pyretis|, but they should be
introduced in a way that does not make the normal documentation build
fragile. The easiest path is to start with the pure-Python internal
examples and keep the external-engine examples as downloadable input
sets.

Recommended first step
======================

Create one notebook for each lightweight internal tutorial:

* TIS in a 1D potential.
* RETIS in a 1D potential.
* Sub-moves on a 1D potential.
* Plain MD and MD-flux setup.

Each notebook should run in a few minutes, generate one or two plots,
and link back to the corresponding full documentation page. The source
of truth should remain the same input files used by the examples and
the regression tests, so the notebook is a guided front end rather than
a separate example that can drift.

Documentation integration
=========================

There are two low-maintenance ways to publish these notebooks:

* **Notebook links in the examples pages.** Store notebooks under
  ``examples/notebooks/`` and link to them from the relevant pages.
  This is the smallest change and works immediately.
* **Rendered notebooks in Sphinx.** Add ``nbsphinx`` or
  ``myst-nb`` later and render selected notebooks into the website.
  This gives a richer website, but the docs build must then decide
  whether notebooks are executed during CI or rendered from saved
  outputs.

For a hosted interactive session, Binder is the practical first target:
it can install the Python dependencies and run the pure-Python examples
without requiring users to install |pyretis| locally. JupyterLite can be
considered later for tiny browser-only demos, but it is a tighter fit
because |pyretis| uses scientific Python dependencies and some examples
need file-system output.

Suggested implementation plan
=============================

1. Add ``examples/notebooks/tis-1d.ipynb`` and keep it under five
   visible cells: import, load settings, run, analyse, plot.
2. Add a small ``environment.yml`` or ``requirements-notebooks.txt`` for
   Binder.
3. Add a notebook smoke test that runs the notebook with
   ``jupyter nbconvert --execute`` or ``pytest --nbmake``.
4. Link the notebook from :ref:`examples-tis-1d` and this page.
5. Repeat for RETIS and sub-moves once the first notebook is stable.

This keeps the interactive work incremental: the website can advertise
the direction now, while the normal examples and regression checks stay
fully usable without a notebook stack.