perf: cap PyTorch threads, bump fix_illumination forks, skip intermediate pyramids

docs/LIBRARY_MODULES.md

@@ -51,13 +51,13 @@ from linumpy.io.thorlabs import ThorImageOCT
 point: it materialises the requested level into memory and returns
 `(array, voxel_size)`. With ``use_gpu=False`` (default) the array is a
 ``numpy.ndarray``; with ``use_gpu=True`` it dispatches through
-[`linumpy.gpu.zarr_io.read_zarr_to_gpu`](GPU_ACCELERATION.md) and returns a
+`linumpy.gpu.zarr_io.read_zarr_to_gpu` (see {doc}`GPU_ACCELERATION`) and returns a
 ``cupy.ndarray`` (kvikio/GPUDirect Storage when available, otherwise the
 ``zarr.config.enable_gpu`` fallback). Voxel size is ordered to match the array
 axes (Z, Y, X for 3D volumes; Y, X for 2D mosaics).
 
-See [Mosaic Grid Format](MOSAIC_GRID_FORMAT.md) and
-[Slice Config Feature](SLICE_CONFIG_FEATURE.md) for format details.
+See {doc}`Mosaic Grid Format <MOSAIC_GRID_FORMAT>` and
+{doc}`Slice Config Feature <SLICE_CONFIG_FEATURE>` for format details.
 
 ### `linumpy.cli` and `linumpy.config`
 
@@ -84,7 +84,7 @@ from linumpy.metrics import (
 )
 ```
 
-See [Reconstruction Diagnostics](RECONSTRUCTION_DIAGNOSTICS.md).
+See {doc}`Reconstruction Diagnostics <RECONSTRUCTION_DIAGNOSTICS>`.
 
 ### `linumpy.geometry`
 
@@ -146,7 +146,7 @@ CuPy-backed versions of hot paths. Each public entry point either takes a
   fastest backend available (kvikio/GDS native → `zarr.config.enable_gpu`).
 * `gpu.kvikio_zarr` — kvikio / GPUDirect Storage backend for the dispatcher.
 
-See [GPU Acceleration](GPU_ACCELERATION.md) and [N4 GPU](N4_GPU.md).
+See {doc}`GPU Acceleration <GPU_ACCELERATION>` and {doc}`N4 GPU <N4_GPU>`.
 
 ### `linumpy.stack_alignment`
 
@@ -158,7 +158,7 @@ from linumpy.stack_alignment.units import detect_shift_units
 from linumpy.stack_alignment.filter import filter_outliers
 ```
 
-See [Shifts File Format](SHIFTS_FILE_FORMAT.md).
+See {doc}`Shifts File Format <SHIFTS_FILE_FORMAT>`.
 
 ### `linumpy.imaging`
 
@@ -207,11 +207,11 @@ A typical pipeline run wires these subpackages as follows:
    `gpu.n4` backend when CUDA is available) and `imaging.orientation` / RAS
    alignment via `reference.allen`.
 7. **Diagnostics** use `metrics` collectors throughout; see
-   [Reconstruction Diagnostics](RECONSTRUCTION_DIAGNOSTICS.md).
+   {doc}`Reconstruction Diagnostics <RECONSTRUCTION_DIAGNOSTICS>`.
 
 ## See also
 
 * Auto-generated API reference: [api/linumpy](api/linumpy/index.rst)
-* [Pipeline Overview](PIPELINE_OVERVIEW.md)
-* [Scripts Reference](SCRIPTS_REFERENCE.md)
-* [Nextflow Workflows](NEXTFLOW_WORKFLOWS.md)
+* {doc}`Pipeline Overview <PIPELINE_OVERVIEW>`
+* {doc}`Scripts Reference <SCRIPTS_REFERENCE>`
+* {doc}`Nextflow Workflows <NEXTFLOW_WORKFLOWS>`

docs/N4_GPU.md

@@ -134,7 +134,7 @@ server.
 ## 5. Performance
 
 Benchmarks measured on a single NVIDIA GPU (47 GB) using the
-`linum_benchmark_n4_gpu` script (see [Scripts reference](SCRIPTS_REFERENCE.md)).
+`linum_benchmark_n4_gpu` script (see {doc}`SCRIPTS_REFERENCE`).
 The CPU path is `SimpleITK.N4BiasFieldCorrectionImageFilter` with the same
 control-point spacing and iteration schedule as the GPU path. Both paths
 include the `shrink_factor` downsample. The GPU column already excludes a
@@ -218,7 +218,7 @@ directory.
 
 The Nextflow `reconst_3d` workflow exposes a single global GPU switch
 (`params.use_gpu`, defined in the reconst_3d Nextflow config; see
-[Nextflow workflows](NEXTFLOW_WORKFLOWS.md)).
+{doc}`Nextflow workflows <NEXTFLOW_WORKFLOWS>`).
 When set, the `correct_bias_field` process runs the GPU N4 backend with
 `maxForks = 1` to avoid GPU contention; otherwise it uses the SimpleITK
 CPU path with `params.processes` threads. No per-process flag is needed:

docs/NEXTFLOW_WORKFLOWS.md

@@ -269,7 +269,7 @@ gaps are not interpolated (insufficient information) and remain as holes.
 
 When zmorph's quality gates fail the slot is left as a genuine gap (no zarr
 output); a manifest fragment and diagnostics JSON are still emitted. See
-[SLICE_INTERPOLATION_FEATURE.md](SLICE_INTERPOLATION_FEATURE.md) for details.
+{doc}`SLICE_INTERPOLATION_FEATURE` for details.
 
 #### Automatic Slice Quality Assessment
 
@@ -638,7 +638,7 @@ params {
 For GPU support:
 - NVIDIA GPU with CUDA support
 - CuPy installed: `uv pip install cupy-cuda12x`
-- See [GPU_ACCELERATION.md](GPU_ACCELERATION.md) for detailed setup
+- See {doc}`GPU_ACCELERATION` for detailed setup
 
 ### Expected Speedups
 
@@ -1124,7 +1124,7 @@ without exhaustion.
 zmorph's quality gates reject the interpolation it emits a manifest fragment
 with `interpolation_failed=true` and no zarr; `finalise_interpolation`
 stamps that into `slice_config_final.csv` and the slot stays a genuine gap
-in the stacked volume. See [`SLICE_INTERPOLATION_FEATURE.md`](SLICE_INTERPOLATION_FEATURE.md)
+in the stacked volume. See {doc}`SLICE_INTERPOLATION_FEATURE`
 for the full policy.
 
 ### `finalise_interpolation` is published-only

docs/PIPELINE_OVERVIEW.md

@@ -47,8 +47,6 @@ flowchart TD
     P3 --> INTER
     INTER --> R00
     INTER --> R01
-    R14 --> OUT
-    R14b --> OUT
     R16 --> OUT
 
     classDef opt fill:#f5f5f5,stroke:#999,stroke-dasharray:3 3,color:#555
@@ -273,7 +271,7 @@ interpolate_missing_slice
 - Fills single-slice gaps using the two neighbouring slices
 - Enabled by `interpolate_missing_slices = true` (default)
 - Default method is **zmorph** (z-aware morphing via fractional affine
-  transforms on the boundary planes) — see [SLICE_INTERPOLATION_FEATURE.md](SLICE_INTERPOLATION_FEATURE.md)
+  transforms on the boundary planes) — see {doc}`SLICE_INTERPOLATION_FEATURE`
 - When zmorph's quality gates fail the slot stays a genuine gap (no zarr
   emitted) — nothing is fabricated
 - `finalise_interpolation` merges per-slice manifest fragments into
@@ -664,7 +662,7 @@ nextflow run preproc_rawtiles.nf --input /path/to/data --output /path/to/output
 
 - NVIDIA GPU with CUDA support
 - CuPy installed (`uv pip install cupy-cuda12x`)
-- See [GPU_ACCELERATION.md](GPU_ACCELERATION.md) for detailed setup
+- See {doc}`GPU_ACCELERATION` for detailed setup
 
 ---