tompollard · Oct 28, 2026 · Oct 27, 2026 · Oct 27, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
@@ -1,2 +1,8 @@
 # Apply ruff formatting and safe lint fixes
 8790758451dfde249db2c31d4cc4ff13f5106fd2
+
+# Wrap docstrings and comments at 88 columns
+fbe3d8048f4711fc09da647a8cf2bf4c2e4a8673
+
+# Start docstrings on the opening quote line with a one-line summary
+1594919c9ce5a8dcc4af83c253cc5411f2492df2
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -17,4 +17,4 @@ jobs:
       - name: Install Python
         run: uv python install 3.12
       - name: Build documentation
-        run: uv run --python 3.12 --only-group docs make -C docs html
+        run: uv run --python 3.12 --only-group docs make -C docs html SPHINXOPTS="-W --keep-going"
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,32 @@
+# AGENTS.md
+
+WFDB-Python is a library for reading, writing and processing physiologic signals and annotations in the WFDB format. See [DEVELOPING.md](DEVELOPING.md) for the full contributor guide.
+
+## Layout
+
+- `src/wfdb/`: the package (`io`, `plot`, `processing`)
+- `tests/`: pytest tests, which read sample files from `sample-data/` relative to the repository root, so run them from there
+- `docs/`: Sphinx documentation, including the changelog in `docs/changes.rst`
+
+## Commands
+
+The project uses [uv](https://docs.astral.sh/uv/). `uv run` installs the `dev` dependency group automatically.
+
+```sh
+uv run pytest                     # all tests
+uv run pytest -m "not network"    # only tests that work offline
+uv run pytest -n auto             # in parallel
+uv run ruff format .              # format
+uv run ruff check .               # lint
+uv run --only-group docs make -C docs html SPHINXOPTS="-W --keep-going"
+```
+
+## Conventions
+
+- Format and lint with Ruff before committing. Lines (including docstrings and comments) are at most 88 columns.
+- Docstrings use the numpy style. Start the docstring directly after the opening quotes with a summary that fits on one line, followed by a blank line and the details (if any).
+- The docs build treats warnings as errors, so check it after changing a docstring.
+- Tests are plain pytest functions or classes (no `unittest`). Tests that need PhysioNet are marked `network` and are skipped if PhysioNet cannot be reached. Where possible, a test has a `local` variant and a `physionet` variant through the `source` fixture.
+- Add a changelog entry to `docs/changes.rst` for user-visible changes.
+- The version is set in `pyproject.toml` only. Do not bump it as part of a feature or fix.
+- Commits that only reformat code are listed in `.git-blame-ignore-revs`.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+See @AGENTS.md for guidance on working with this repository.
diff --git a/DEVELOPING.md b/DEVELOPING.md
@@ -4,7 +4,7 @@
 
 We welcome community contributions in the form of pull requests. When contributing code, please ensure:
 
-- Documentation is provided. New functions and classes should have numpy/scipy style [docstrings](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt).
+- Documentation is provided. New functions and classes should have numpy/scipy style [docstrings](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt). Start the docstring on the line of the opening quotes, with a summary that fits on a single line (the documentation build fails on warnings, so check it with `uv run --only-group docs make -C docs html SPHINXOPTS="-W --keep-going"`).
 - Unit tests are written for new features that are not covered by [existing tests](https://github.com/MIT-LCP/wfdb-python/tree/main/tests).
 - The code style is consistent with the project's formating standards.
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -20,7 +20,7 @@
 import sys
 import tomllib
 
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../src"))
 
 # For dependencies
 from unittest.mock import MagicMock
@@ -49,6 +49,10 @@ def __getattr__(cls, name):
     "numpydoc",
 ]
 
+# The class members are documented by the autoclass directives, so don't link the
+# method tables to (non-existent) autosummary stubs.
+numpydoc_class_members_toctree = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

diff --git a/docs/io.rst b/docs/io.rst
@@ -12,21 +12,25 @@ WFDB Records
     :members: rdrecord, rdheader, rdsamp, wrsamp
 
 .. autoclass:: wfdb.io.Record
+    :no-index:
     :members: get_frame_number, get_elapsed_time, get_absolute_time,
               wrsamp, adc, dac, to_dataframe
 
 .. autoclass:: wfdb.io.MultiRecord
+    :no-index:
     :members: get_frame_number, get_elapsed_time, get_absolute_time,
               multi_to_single, contained_ranges, contained_combined_ranges
 
 
 WFDB Annotations
----------------
+----------------
 
 .. automodule:: wfdb.io
+    :no-index:
     :members: rdann, wrann, show_ann_labels, show_ann_classes
 
 .. autoclass:: wfdb.io.Annotation
+    :no-index:
     :members: wrann
 
 
@@ -86,4 +90,5 @@ Downloading
 -----------
 
 .. automodule:: wfdb.io
+    :no-index:
     :members: dl_files, dl_database, get_dbs, get_record_list, set_db_index_url
diff --git a/docs/processing.rst b/docs/processing.rst
@@ -17,30 +17,35 @@ Heart Rate
 ----------
 
 .. automodule:: wfdb.processing
+    :no-index:
     :members: compute_hr, calc_rr, calc_mean_hr, ann2rr, rr2ann
 
 
 Peaks
 -----
 
 .. automodule:: wfdb.processing
+    :no-index:
     :members: find_peaks, find_local_peaks, correct_peaks
 
 Filters
 -------
 
 .. automodule:: wfdb.processing
+    :no-index:
     :members: sigavg
 
 QRS Detectors
 -------------
 
 .. automodule:: wfdb.processing
+    :no-index:
     :members: XQRS, xqrs_detect, gqrs_detect
 
 
 Annotation Evaluators
 ---------------------
 
 .. automodule:: wfdb.processing
+    :no-index:
     :members: Comparitor, compare_annotations, benchmark_mitdb
diff --git a/docs/wfdb.rst b/docs/wfdb.rst
@@ -21,9 +21,10 @@ WFDB Records
 
 
 WFDB Annotations
----------------
+----------------
 
 .. automodule:: wfdb
+    :no-index:
     :members: rdann, wrann, show_ann_labels, show_ann_classes
 
 .. autoclass:: wfdb.Annotation
@@ -34,11 +35,13 @@ Downloading
 -----------
 
 .. automodule:: wfdb
+    :no-index:
     :members: dl_files, dl_database, get_dbs, get_record_list, set_db_index_url
 
 
 Plotting
 --------
 
 .. automodule:: wfdb
+    :no-index:
     :members: plot_items, plot_wfdb, plot_all_records
diff --git a/pyproject.toml b/pyproject.toml
@@ -37,7 +37,7 @@ dev = [
 docs = [
     "fsspec >= 2023.10.0",
     "numpydoc == 1.7.0",
-    "sphinx == 7.0.0",
+    "sphinx == 7.2.6",
 ]
 
 [tool.ruff]
@@ -62,6 +62,10 @@ ignore = [
     "B905",
 ]
 
+[tool.ruff.lint.pycodestyle]
+# Wrap docstrings and comments at the same width as the code
+max-doc-length = 88
+
 [tool.ruff.lint.per-file-ignores]
 # Re-exports
 "__init__.py" = ["F401"]
@@ -71,6 +75,3 @@ addopts = "-r s"
 markers = [
     "network: requires access to PhysioNet (skipped if it cannot be reached)",
 ]
-
-[tool.uv.build-backend]
-module-root = ""
diff --git a/wfdb/__init__.py → src/wfdb/__init__.py b/wfdb/__init__.py → src/wfdb/__init__.py
diff --git a/wfdb/io/__init__.py → src/wfdb/io/__init__.py b/wfdb/io/__init__.py → src/wfdb/io/__init__.py
diff --git a/wfdb/io/_coreio.py → src/wfdb/io/_coreio.py b/wfdb/io/_coreio.py → src/wfdb/io/_coreio.py
@@ -20,8 +20,7 @@ def _open_file(
     newline=None,
     check_access=False,
 ):
-    """
-    Open a data file as a random-access file object.
+    """Open a data file as a random-access file object.
 
     See the documentation of `open` and `wfdb.io._url.openurl` for details
     about the `mode`, `buffering`, `encoding`, `errors`, and `newline`
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# CLAUDE.md

		See @AGENTS.md for guidance on working with this repository.