add readthedocs (#28)

Author: phoeenniixx

.github/workflows/test.yml

@@ -73,6 +73,36 @@ jobs:
         run: build_tools/run_examples.sh
         shell: bash
 
+  docs:
+    name: Build docs
+    needs: code-quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      # nbsphinx shells out to the pandoc binary for the notebooks'
+      # markdown cells. The "pandoc" PyPI package does not provide it.
+      - name: Install pandoc
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[docs]"
+
+      - name: Show dependencies
+        run: python -m pip list
+
+      # -W turns warnings into errors, so a docstring with broken RST fails
+      # here instead of rendering wrong on the published site.
+      - name: Build docs
+        run: python -m sphinx -b html docs docs/_build/html -W --keep-going
+
   pytest-nosoftdeps:
     name: no-softdeps
     needs: code-quality

.gitignore

@@ -103,3 +103,6 @@ dmypy.json
 checkpoints/
 lightning_logs/
 .DS_Store
+
+# sphinx build output
+docs/_build/

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs build configuration.
+# https://docs.readthedocs.com/platform/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  apt_packages:
+    # nbsphinx shells out to the pandoc binary to render the notebooks'
+    # markdown cells; the "pandoc" PyPI package is only a wrapper around it.
+    - pandoc
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: uv
+      command: pip
+      path: .
+      extras:
+        - docs

README.md

@@ -1,7 +1,7 @@
 # PyQit
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Status: Active Development](https://img.shields.io/badge/status-active_development-orange.svg)]()
+![Status: Active Development](https://img.shields.io/badge/status-active_development-orange.svg)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg)](https://github.com/astral-sh/ruff)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/phoeenniixx/pyQit/test.yml)](https://github.com/phoeenniixx/pyqit/actions)
 
@@ -11,7 +11,7 @@
 
 **Version `0.1.0b1`. The API is unstable and still changing.**
 
-### Key Features
+## Key Features
 
 * **Lightweight & Modular:** PyQit runs natively on **PennyLane** and **NumPy**.
     > **PyTorch and PyTorch Lightning are strictly optional soft dependencies.** If you don't need deep learning hybrid models or GPU orchestration, you don't have to install them.

docs/Makefile

@@ -0,0 +1,17 @@
+# Minimal makefile for Sphinx documentation.
+# Run "make html" from this directory, then open _build/html/index.html.
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= python -m sphinx
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all: route anything else to sphinx-build's -M mode.
+# Gives html, clean, linkcheck and the rest with no target per command.
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api/ansatzes.rst

@@ -0,0 +1,40 @@
+========
+Ansatzes
+========
+
+.. currentmodule:: pyqit.ansatzes
+
+An ansatz is the trainable part of the circuit. A model builds one from the
+class you hand it, using the model's own qubit count.
+
+.. code-block:: python
+
+   from pyqit.ansatzes import SELAnsatz
+   from pyqit.models import VQCClassifier
+
+   model = VQCClassifier(n_qubits=4, n_layers=3, ansatz=SELAnsatz)
+
+:class:`SELAnsatz` wraps PennyLane's strongly entangling layers. Depth comes from
+the model's ``n_layers``. More layers buy expressivity and cost you gradient
+variance, which is what the barren-plateau check measures.
+
+To add your own, subclass :class:`BaseAnsatz` and give it an ``object_type`` tag
+of ``"ansatz"``. Implement ``get_test_params()`` and the suite enrolls it
+automatically. See :doc:`the contributing guide </contributing>`.
+
+Related
+=======
+
+A :doc:`model <models>` builds the ansatz you give it. Depth is where gradients
+go to die, so pair this with :doc:`diagnostics` and the
+:doc:`barren-plateau tutorial </tutorials/barren_plateau>` before reaching for
+more layers.
+
+.. autosummary::
+   :nosignatures:
+
+   BaseAnsatz
+   SELAnsatz
+
+.. autoclass:: BaseAnsatz
+.. autoclass:: SELAnsatz

docs/api/callbacks.rst

@@ -0,0 +1,99 @@
+=========
+Callbacks
+=========
+
+.. currentmodule:: pyqit.core.callbacks
+
+A pyqit callback implements up to three hooks, ``on_fit_start``,
+``on_epoch_end`` and ``on_fit_end``, each taking one :class:`LoopState`. Write it
+once and both backends honour it.
+
+.. code-block:: python
+
+   import pyqit
+   from pyqit.core import EarlyStopping, ModelCheckpoint
+
+   trainer = pyqit.Trainer(
+       max_epochs=100,
+       loss_fn="cross_entropy",
+       callbacks=[
+           EarlyStopping(monitor="val_loss", patience=3),
+           ModelCheckpoint(dirpath="ckpts", save_best=True, save_last=True),
+       ],
+   )
+   history = trainer.fit(model, dm)
+
+.. code-block:: text
+
+   [EarlyStopping] Stopped at epoch 18 - val_loss did not improve for 3 epoch(s)
+   [Checkpoint] Restored best weights from epoch 15 (val_loss: 0.3721)
+
+Why Lightning callbacks are rejected
+====================================
+
+They are typed against Lightning's hooks, so the PennyLane loop could only
+ignore them. An ignored :class:`EarlyStopping` hands back a fully trained model
+without saying so, and that failure is invisible. Rejecting them at the door is
+the louder option.
+
+On the torch backend a shim reads Lightning's ``callback_metrics`` into the same
+metric names and forwards ``state.stop`` onto ``trainer.should_stop``, so the
+same callback object works on both sides.
+
+Checkpointing
+=============
+
+:class:`ModelCheckpoint` owns checkpointing on both backends, and Lightning's
+own is switched off so a run is never written twice. Only the file format
+differs, ``.ckpt`` holding a ``state_dict`` on torch and ``.npz`` on pennylane.
+The array keys match ``model.weights`` either way.
+
+Three files can be written independently. ``save_best`` uses the stem from
+``filename``, ``save_last`` uses ``last``, and ``every_n_epochs`` uses
+``epoch<n>``, numbered from zero to match ``best_epoch``. The best file is
+written once after training. Set ``save_on_improve=True`` to write on every
+improvement instead, at the cost of extra I/O.
+
+``restore_best`` defaults to whatever ``save_best`` is, not to ``True``, so
+``save_best=False, save_last=True`` will not quietly hand you back the best
+model when you asked for the last one.
+
+Nothing here resumes a run. These files hold weights only, with no optimizer
+state and no epoch counter.
+
+Writing your own
+================
+
+.. code-block:: python
+
+   from pyqit.core import BaseCallback
+
+   class StopWhenConverged(BaseCallback):
+       def on_epoch_end(self, state):
+           if state.metrics["train_loss"] < 0.01:
+               state.stop = True
+
+``state`` carries the model, datamodule, history, reporter, epoch index and this
+epoch's metrics. ``state.stop`` is the one field a callback may write.
+
+Related
+=======
+
+:doc:`trainer` takes the ``callbacks`` list and assembles it. The
+:doc:`callbacks tutorial </tutorials/callbacks>` runs both built-in callbacks
+together and reloads the checkpoint afterwards.
+
+.. autosummary::
+   :nosignatures:
+
+   BaseCallback
+   LoopState
+   HistoryCallback
+   EarlyStopping
+   ModelCheckpoint
+
+.. autoclass:: BaseCallback
+.. autoclass:: LoopState
+.. autoclass:: HistoryCallback
+.. autoclass:: EarlyStopping
+.. autoclass:: ModelCheckpoint

docs/api/config.rst

@@ -0,0 +1,71 @@
+=============
+Configuration
+=============
+
+.. currentmodule:: pyqit
+
+Backend selection is global, not per object. :func:`set_backend` writes to a
+context variable, and every object reads it once in its own ``__init__`` and
+caches the answer.
+
+.. code-block:: python
+
+   import pyqit
+   from pyqit.models import VQCClassifier
+
+   pyqit.set_backend("torch")               # first
+   model = VQCClassifier(n_qubits=4)        # then
+
+Order matters and getting it wrong fails quietly. Setting the backend after you
+build a model leaves that model on the old one.
+
+:func:`set_backend` raises :class:`ImportError` when you ask for ``"torch"``
+without torch installed. Every torch import in the package sits behind either
+this call or a runtime type check, so the one guard covers them all and the
+error names its own cause instead of surfacing later as a bare
+``ModuleNotFoundError``.
+
+What the backend changes
+========================
+
+Three things fork on it. The QNode is wrapped in a ``qml.qnn.TorchLayer`` or
+stored as plain ``pnp`` arrays. Training runs through Lightning or through a
+PennyLane optimizer loop. Loaders come from ``torch.utils.data`` or from an
+internal NumPy loader.
+
+Seeding
+=======
+
+:func:`set_seed` seeds NumPy, which covers PennyLane too because
+``pennylane.numpy.random`` delegates to it, and seeds torch when it is
+installed. :meth:`Trainer.fit <pyqit.core.Trainer.fit>` calls it before anything
+stochastic runs.
+
+Weights are drawn at construction, so reproducing them means seeding first:
+
+.. code-block:: python
+
+   pyqit.set_seed(42)
+   model = VQCClassifier(n_qubits=4)
+
+``Trainer(seed=...)`` alone covers training and diagnostics, not
+initialisation. Note that this mutates global RNG state, the same contract as
+Lightning's ``seed_everything``.
+
+Related
+=======
+
+:doc:`models` and :doc:`trainer` both read the backend at construction, which is
+why the order on this page matters. :doc:`datamodule` picks its loader from the
+same setting.
+
+.. autosummary::
+   :nosignatures:
+
+   set_backend
+   get_backend
+   set_seed
+
+.. autofunction:: set_backend
+.. autofunction:: get_backend
+.. autofunction:: set_seed

docs/api/datamodule.rst

@@ -0,0 +1,67 @@
+==========
+DataModule
+==========
+
+.. currentmodule:: pyqit
+
+:class:`DataModule` holds the data and does nothing with it until ``setup()``
+runs. :meth:`Trainer.fit <pyqit.core.Trainer.fit>` and
+:meth:`Trainer.predict <pyqit.core.Trainer.predict>` call ``setup()`` for you,
+which is why properties like ``X_train`` raise before then.
+
+.. code-block:: python
+
+   import pyqit
+   from sklearn.datasets import make_moons
+
+   X, y = make_moons(n_samples=200, noise=0.1, random_state=0)
+   dm = pyqit.DataModule(X, y, normalize="minmax", batch_size=16)
+
+What setup does, in order
+=========================
+
+#. Split into train, val and test.
+#. Normalize. This step is stateful, so the normalizer fits on train only and
+   then applies to val and test. ``minmax``, ``zscore``, ``l1`` and ``l2`` are
+   built in.
+#. Prescale for the circuit. This step is stateless and the model's embedding
+   drives it, not the user.
+#. Apply any ``transform``.
+
+Prescaling explains why feature shaping is not your job. ``AngleEmbedding`` pads
+or truncates to ``n_qubits`` and multiplies by pi. ``AmplitudeEmbedding`` pads to
+``2 ** n_qubits`` and L2-normalizes. The model class picks the embedding, so the
+model class decides the shape.
+
+Repeated setup
+==============
+
+``setup()`` returns early if it already ran, unless you pass ``force=True``. Two
+things sidestep that early return. ``batch_size`` applies every time, because it
+only affects loader construction and never the split or the fitted normalizer,
+so ``Trainer(batch_size=...)`` can override a datamodule you set up by hand.
+``encoder`` and ``n_qubits`` are overwritten only when actually supplied, so they
+survive a later ``setup(force=True)`` that omits them.
+
+Building from tables
+====================
+
+.. code-block:: python
+
+   dm = pyqit.DataModule.from_dataframe(df, label_col="target", normalize="zscore")
+   dm = pyqit.DataModule.from_csv("data.csv", label_col="target")
+
+Related
+=======
+
+:doc:`embeddings` explains the prescaling step and why the model decides input
+shaping. :doc:`trainer` calls ``setup()`` for you. :doc:`pipeline` rebuilds a
+datamodule between sequential stages. Every
+:doc:`tutorial </tutorials/index>` starts by building one.
+
+.. autosummary::
+   :nosignatures:
+
+   DataModule
+
+.. autoclass:: DataModule