Numpy docstrings

.github/workflows/static_analysis.yml

@@ -74,6 +74,17 @@ jobs:
           pip install ruff
           ruff check src/ tests/
 
+  numpydoc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the code
+        uses: actions/checkout@v4
+
+      - name: Docstring sections with numpydoc
+        run: |
+          pip install . numpydoc
+          python -m numpydoc lint $(git ls-files 'src/cunumpy/*.py' 'src/cunumpy/**/*.py' | grep -v _fake_cupy)
+
   pylint:
     runs-on: ubuntu-latest
     continue-on-error: true

.github/workflows/testing.yml

@@ -72,11 +72,15 @@ jobs:
         run: |
           pytest .
 
+      - name: Run docstring examples
+        run: |
+          pytest --doctest-modules src/cunumpy
+
       - name: Test docs build
         run: |
           pip install ".[docs]"
           cd docs
           make clean
-          make html
+          make html SPHINXOPTS="-W --keep-going"
           cd ..
           ls docs/build/html/index.html

CHANGELOG.md

@@ -12,10 +12,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   copy-back, run in CPU CI with fake CuPy and required compilation.
 - Publishing now requires CPU and GPU validation of the release commit, checks
   the built distributions, and smoke-tests the wheel in a fresh environment.
+- NumPy-format docstrings with runnable examples for the whole public API. The
+  API reference is generated from them (`docs/source/reference/`); the
+  hand-written `api.md` is now a short overview, and the CUDA headers have
+  their own page. CI checks the docstrings (ruff `D` rules, numpydoc
+  validation), runs their examples as doctests, and builds the docs with
+  warnings as errors. Docstring style: `docs/source/contributing.md`.
 
 ### Fixed
 - The ordering guide identifies 0.6.3 as the first release preserving F order
   in CuPy-to-host conversions.
+- `CudaStruct.from_signature` accepts quoted pyccel annotations
+  (`markers: "float[:, :]"`) in modules with `from __future__ import annotations`.
 
 ## [0.6.3] - 2026-10-08
 

README.md

@@ -299,8 +299,9 @@ positional argument 0 is written, avoiding unnecessary copy-back for
 read-only inputs. For a keyword call, declare the keyword name, such as
 `outputs=("out",)`. A wrong declaration can leave GPU output values stale.
 The wrapper can also traverse arrays nested in lists, tuples, dictionaries,
-and selected application objects; see the full [API reference](docs/source/api.md)
-for `object_modules`, `is_array`, aliasing, and output declarations.
+and selected application objects; see [Host kernels with GPU
+data](docs/source/kernels/pyccel-kernel.md) for `object_modules`, `is_array`,
+aliasing, and output declarations.
 
 ## Write CUDA kernels next to host kernels
 
@@ -435,8 +436,9 @@ Launches can be 1D to 3D (`n_threads=(nx, ny)`, `block_size=(16, 16)`) or use
 an explicit `grid`, with dynamic shared memory (`shared_mem`) and a `stream`.
 C++ function templates are instantiated with `template_args`, and
 `CudaKernelVariants` caches kernels whose source is generated per variant
-(e.g. per dimension and dtype). See the [API reference](docs/source/api.md) for
-details.
+(e.g. per dimension and dtype). See [Writing CUDA
+kernels](docs/source/kernels/cuda-kernel.md) and [CUDA
+headers](docs/source/kernels/cuda-headers.md) for details.
 
 Kernels run asynchronously, so a CUDA error (an illegal memory access, say)
 normally surfaces at a later `.get()` or MPI call, far from the kernel that
@@ -523,8 +525,9 @@ published at <https://max-models.github.io/cunumpy/>:
 * [Worked examples](docs/source/examples/index.md),
   [best practices](docs/source/best-practices.md),
   [troubleshooting](docs/source/troubleshooting.md),
-  [Pyodide](docs/source/pyodide.md) and the
-  [API reference](docs/source/api.md).
+  [Pyodide](docs/source/pyodide.md), the
+  [API overview](docs/source/api.md) and the
+  [API reference](docs/source/reference/index.md).
 
 ### For AI coding assistants
 

conftest.py

@@ -0,0 +1,17 @@
+"""Doctest setup: examples assume ``import cunumpy as xp`` and ``import numpy as np``."""
+
+import numpy as np
+import pytest
+
+import cunumpy as xp
+
+
+@pytest.fixture(autouse=True)
+def _doctest_namespace(request, doctest_namespace):
+    if not isinstance(request.node, pytest.DoctestItem):
+        yield  # leave the backend of the regular tests alone
+        return
+    doctest_namespace["np"] = np
+    doctest_namespace["xp"] = xp
+    with xp.use_backend("numpy"):
+        yield