docs: make README a general front door; move candide detail to container.md

The README had tunnel-visioned onto a candide-specific SLURM walkthrough —
wrong altitude for the project's landing page, where the broader community
arrives. Restructure it as a front door: a one-sentence-deeper description of
what ShapePipe does, a Quickstart that runs the bundled example straight from
the published container in one command (apptainer or docker, no install, no
cluster specifics), the image tag scheme, and a Documentation signpost to the
published pages.

Move the candide cluster walkthrough (quota-safe pull -> sbatch candide_smp.sh,
the SPDIR bind-mount, the MPI PMIx note) into a new "Running on a cluster
(SLURM)" section in container.md, which the README links to. Drop the
test-assertion prose ("logs ... and exits 0") that read like a CI check rather
than user docs.

Both quickstart commands verified on candide against :develop-runtime
(including the no-pre-pull `apptainer exec docker://...` form): the bundled
example runs to completion, 0 errors.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cailmdaley

README.rst

@@ -16,44 +16,40 @@ ShapePipe
   :target: https://github.com/CosmoStat/shapepipe/releases/latest
 
 ShapePipe is a galaxy shape measurement pipeline developed within the
-CosmoStat lab at CEA Paris-Saclay.
+CosmoStat lab at CEA Paris-Saclay. It runs the full chain from raw survey
+images to calibrated shear catalogues — object detection, PSF modelling, and
+shape measurement — and produced the first UNIONS cosmic-shear release.
 
-See the `documentation <https://cosmostat.github.io/shapepipe>`_ for details
-on how to install and run ShapePipe.
+Quickstart
+----------
 
-Quickstart on a cluster (candide)
----------------------------------
-
-ShapePipe ships as a container image — the supported way to run it (see
-``docs/source/container.md``). On a SLURM cluster such as candide, pull the slim
-``runtime`` image once and submit the bundled example, which runs the pipeline
-on a single CFIS tile:
+ShapePipe ships as a container image, so you can run the bundled example
+pipeline — a single CFIS tile through the full chain — without installing
+anything:
 
 .. code-block:: bash
 
-    # 0. Get a clone (holds the example configs, data, and job scripts).
-    git clone https://github.com/CosmoStat/shapepipe.git
-    cd shapepipe
+    # Apptainer (HPC, no root needed):
+    apptainer exec docker://ghcr.io/cosmostat/shapepipe:develop-runtime shapepipe_run_example
+
+    # ...or Docker:
+    docker run --rm ghcr.io/cosmostat/shapepipe:develop-runtime shapepipe_run_example
 
-    # 1. Keep the SIF and Apptainer's scratch off the quota-limited $HOME.
-    #    candide's home quota is tight; a pull there fails with "disk quota
-    #    exceeded". Point both at a roomy data partition instead.
-    export DATA=/n17data/$USER                 # adjust to your data partition
-    export APPTAINER_CACHEDIR=$DATA/.apptainer
+The image is published on every push to the `GitHub Container Registry
+<https://github.com/CosmoStat/shapepipe/pkgs/container/shapepipe>`_:
+``:develop`` tracks the integration branch, release tags (e.g. ``:v1.1.0``) a
+stable cut, and the ``-runtime`` suffix selects the slim batch image over the
+full interactive one.
 
-    # 2. Pull the runtime image (≈850 MB).
-    apptainer pull "$DATA/shapepipe-runtime.sif" \
-        docker://ghcr.io/cosmostat/shapepipe:develop-runtime
+Documentation
+-------------
 
-    # 3. Submit the example pipeline (SMP, single node).
-    SP_IMAGE="$DATA/shapepipe-runtime.sif" SPDIR="$PWD" \
-        sbatch example/pbs/candide_smp.sh
+Full documentation lives at https://cosmostat.github.io/shapepipe. Good places
+to start:
 
-A clean run logs ``A total of 0 errors were recorded`` and exits ``0``. To span
-multiple nodes with hybrid MPI, swap in ``example/pbs/candide_mpi.sh`` (same two
-variables) — see the comments in each script for the SLURM directives.
+- `Installation <https://cosmostat.github.io/shapepipe/installation.html>`_ — getting ShapePipe onto your machine or cluster.
+- `Basic execution <https://cosmostat.github.io/shapepipe/basic_execution.html>`_ and `configuration <https://cosmostat.github.io/shapepipe/configuration.html>`_ — running ``shapepipe_run`` and writing pipeline configs.
+- `Container workflow <https://cosmostat.github.io/shapepipe/container.html>`_ — the two image targets, the ``pyproject.toml`` / ``uv.lock`` / ``Dockerfile`` layers, and how to run on a SLURM cluster (with a worked candide example).
 
-The ``:develop-runtime`` tag tracks the integration branch; for a stable cut use
-a release tag (e.g. ``:v1.1.0-runtime``). The interactive ``dev`` image (no
-``-runtime`` suffix) carries ``vim``, ``pytest``, and the full toolchain for
-working *inside* the container; ``docs/source/container.md`` covers both.
+If you use ShapePipe in academic work, please cite Guinot et al. (2022) and
+Farrens et al. (2022).

docs/source/container.md

@@ -91,6 +91,44 @@ in, all because something tries to write under `/app` or `$HOME`:
 If you bypass `/tmp` (e.g. with a custom apptainer profile) you may need
 to override these manually.
 
+## Running on a cluster (SLURM)
+
+On a batch cluster you pull the slim `runtime` image once to a SIF, then
+submit a job that runs `shapepipe_run` through it. The repo ships ready
+SLURM scripts for the **candide** cluster in `example/pbs/` —
+`candide_smp.sh` (single node) and `candide_mpi.sh` (multi-node hybrid
+MPI) — that you can copy and adapt. The example below runs the bundled
+single-tile pipeline end to end:
+
+```bash
+# 1. Keep the SIF and Apptainer's scratch off the quota-limited $HOME.
+#    On candide a pull under $HOME fails with "disk quota exceeded";
+#    point both at a roomy data partition instead.
+export DATA=/n17data/$USER                 # adjust to your data partition
+export APPTAINER_CACHEDIR=$DATA/.apptainer
+
+# 2. Pull the runtime image (~850 MB).
+apptainer pull "$DATA/shapepipe-runtime.sif" \
+    docker://ghcr.io/cosmostat/shapepipe:develop-runtime
+
+# 3. Submit the example pipeline. SPDIR is your local clone; it is
+#    bind-mounted at the same path inside the container so the config's
+#    $SPDIR-relative input/output directories resolve identically in and
+#    out of the container.
+SP_IMAGE="$DATA/shapepipe-runtime.sif" SPDIR="/path/to/shapepipe" \
+    sbatch example/pbs/candide_smp.sh
+```
+
+Both job scripts read `SP_IMAGE` (the SIF) and `SPDIR` (the clone) from
+the environment, so the same script serves the example and a real run —
+point the config inside the script at your own pipeline. The MPI script
+additionally needs the host's OpenMPI to match the container's PMIx wire
+protocol; it `module load`s a compatible OpenMPI (the image ships the
+5.0.x series), and the script's header comments explain the contract.
+
+Adapting to another SLURM cluster is mostly the `#SBATCH` directives and
+the `module load` line — the `apptainer exec` invocation carries over.
+
 ## Three configuration layers
 
 Three files determine what the image contains. Each has a clear role; the