Restore the Read the Docs build and refresh the docs

.readthedocs.yaml

@@ -5,13 +5,23 @@
 version: 2
 
 build:
-    os: ubuntu-20.04
+    # Read the Docs removed the ubuntu-20.04 image on 2026-06-01; a build that
+    # still asks for it fails before Sphinx runs. Supported values are
+    # ubuntu-22.04, ubuntu-24.04, ubuntu-26.04, and ubuntu-lts-latest.
+    os: ubuntu-24.04
     tools:
-        python: "3.9"
+        # Only used to run Sphinx. The docs build does not install the package
+        # (conf.py mocks the third-party imports), so this is independent of the
+        # requires-python floor in pyproject.toml.
+        python: "3.12"
 
 sphinx:
     configuration: docs/source/conf.py
+    # The build is warning-free against the pinned Sphinx in
+    # docs/requirements.txt, so a new warning means the docs have drifted from
+    # the code (a renamed object, a dead cross-reference) and should be seen.
+    fail_on_warning: true
 
 python:
    install:
-   - requirements: docs/requirements.txt
+   - requirements: docs/requirements.txt

CLAUDE.md

@@ -15,7 +15,7 @@ network access, no database, no state outside the caller's arrays.
     uv sync                       # install; requires-python >=3.9
     uv run pytest                 # whole suite; seconds, no data files needed
     CCF_STREAMLINES_TEST_DATA=... uv run pytest -m real_data   # opt-in tier, real assets
-    cd docs && make html          # Sphinx docs -> docs/build (needs docs/requirements.txt: sphinx 5.2.3)
+    cd docs && make html          # Sphinx docs -> docs/build (needs docs/requirements.txt: sphinx 9.1.0)
 
 There is no lint, format, or typecheck configuration in the repo.
 `.github/workflows/tests.yml` gates pull requests across x86-64 and ARM64 on Python
@@ -158,8 +158,11 @@ gated. `python-publish.yml` builds and publishes to PyPI on GitHub release.
   there resolves to whatever interpreter uv finds (3.13 in this checkout). Nothing tests 3.9.
 - Dead imports: `itertools` in `projection.py`; `h5py`, `nrrd`, `pandas`, `logging`, and
   `tqdm` in `metrics.py` (only `numpy` and the shared layer-key import are used there).
-- `docs/source/reference/processing.rst` titles itself `ccf_streamlines.projection` — wrong
-  module name in the heading.
+- The Read the Docs build (`.readthedocs.yaml`) is pinned to `ubuntu-24.04` / Python 3.12 and
+  runs with `fail_on_warning: true`. It does not install the package — `conf.py` mocks the
+  third-party imports and regex-scrapes the version out of `pyproject.toml` — so the docs
+  build is independent of the `requires-python` floor. The build is warning-free as pinned;
+  a new Sphinx warning will fail the RTD build rather than land silently.
 - A stale, untracked `ccf_streamlines.egg-info/` sits in the repo root from the pre-uv
   setuptools build. It is not the build source; `uv_build` is (`pyproject.toml`).
 

docs/requirements.txt

@@ -1,2 +1,2 @@
-sphinx==5.2.3
-pydata-sphinx-theme==0.10.1
+sphinx==9.1.0
+pydata-sphinx-theme==0.21.0

docs/source/conf.py

@@ -15,7 +15,7 @@
 
 
 project = 'ccf_streamlines'
-copyright = '2022, Nathan Gouwens'
+copyright = '2022-2026, Allen Institute'
 author = 'Nathan Gouwens'
 
 # Single-sourced from pyproject.toml so the docs cannot drift from the package
@@ -39,9 +39,23 @@
 
 autodoc_mock_imports = ["h5py", "numpy", "scipy", "pandas", "nrrd", "tqdm", "skimage"]
 
+# cell.com answers every non-browser client with a 403, so the Wang et al. (2020)
+# reference is a false positive for `sphinx-build -b linkcheck` rather than a
+# dead link. Everything else in the docs is checked.
+linkcheck_ignore = [
+    r"https://www\.cell\.com/",
+]
+
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'pydata_sphinx_theme'
-html_static_path = ['_static']
+
+# html_static_path is deliberately unset: the tree keeps no _static directory,
+# and pointing the setting at a missing one was the build's only warning.
+
+html_theme_options = {
+    "github_url": "https://github.com/AllenInstitute/ccf_streamlines",
+}
+

docs/source/guide.rst

@@ -19,6 +19,29 @@ memory issues depending on the capabilities of your machine, how many data sets
 or projections you try to use at once, etc.
 
 
+Installation
+------------
+
+``ccf_streamlines`` is published on PyPI and requires Python 3.9 or newer.
+
+.. code:: bash
+
+    pip install ccf-streamlines
+
+The package is imported by submodule, since the top-level package exports only
+``__version__``:
+
+.. code:: python3
+
+    import ccf_streamlines.projection as ccfproj
+
+Installing the package does not bring down any reference data. The streamline,
+view lookup, and atlas files that every projector needs are downloaded
+separately, and are listed in :ref:`Data Files`. The examples throughout this
+guide also use `matplotlib <https://matplotlib.org>`_ for plotting, which is not
+a dependency of the package.
+
+
 What are streamlines?
 ---------------------
 
@@ -51,10 +74,10 @@ Projecting a volume to 2D
 
 This section will present how to use the ``ccf_streamlines`` package to project
 3D CCF-aligned data to two-dimensional views. As an example, we will use the
-`10-micron resolution average template data <http://download.alleninstitute.org/informatics-archive/current-release/mouse_ccf/average_template/average_template_10.nrrd>`_ for the CCF.
+`10-micron resolution average template data <https://download.alleninstitute.org/informatics-archive/current-release/mouse_ccf/average_template/average_template_10.nrrd>`_ for the CCF.
 (**note:** this file is ~300 MB). The file is in the NRRD format.
 
-After downloading the file to the director we're working in, we can load it into a 3D NumPy array.
+After downloading the file to the directory we're working in, we can load it into a 3D NumPy array.
 
 .. code:: python3
 
@@ -83,7 +106,7 @@ process the 3D data.
         "surface_paths_10_v3.h5",
 
         # Specify that we want to project both hemispheres
-        hemisphere="both"
+        hemisphere="both",
 
         # The top view contains space for the right hemisphere, but is empty.
         # Therefore, we tell the projector to put both hemispheres side-by-side
@@ -221,15 +244,15 @@ from different angles, as with the other view types). In this case, we may be
 interested not only in viewing our data across the cortical surface, but also
 throughout the (flattened) cortical depth.
 
-We'll use an `Allen Mouse Brain Connectivity Atlas <http://connectivity.brain-map.org>`_
+We'll use an `Allen Mouse Brain Connectivity Atlas <https://connectivity.brain-map.org>`_
 as an example, since we'll be able to see processes that travel perpendicular
 to the cortical surface (e.g., apical dendrites of labeled neurons).
 
-We'll look at `this experiment <http://connectivity.brain-map.org/projection/experiment/297231636>`_
+We'll look at `this experiment <https://connectivity.brain-map.org/projection/experiment/297231636>`_
 in which cells labeled by the Tlx-Cre driver (primarily excitatory neurons in layer 5a of cortex)
 in the visual area VISal are fluorescent. You can download the projection data with this link:
 
-http://api.brain-map.org/grid_data/download_file/297231636??image=projection_density&resolution=10
+https://api.brain-map.org/grid_data/download_file/297231636??image=projection_density&resolution=10
 
 Once that is downloaded, we will load it as we did the average template.
 
@@ -278,12 +301,12 @@ in 3D.
         view_space_for_other_hemisphere='flatmap_butterfly',
 
         # Additional information for thickness calculations
-        thickness_type="normalized_layers", # each layer will have the same thickness everwhere
+        thickness_type="normalized_layers", # each layer will have the same thickness everywhere
         layer_thicknesses=layer_thicknesses,
         streamline_layer_thickness_file="cortical_layers_10_v2.h5",
     )
 
-Once we have it set up, we can project the data in the same was as in 2D.
+Once we have it set up, we can project the data in the same way as in 2D.
 
 .. code:: python3
 
@@ -523,7 +546,7 @@ class. It is set up in a similar way to the other projectors.
 .. code:: python3
 
     ccf_coord_proj = ccfproj.IsocortexCoordinateProjector(
-        projection_file="flatmap_buttefly.h5",
+        projection_file="flatmap_butterfly.h5",
         surface_paths_file="surface_paths_10_v3.h5",
         closest_surface_voxel_reference_file="closest_surface_voxel_lookup.h5",
         layer_thicknesses=layer_thicknesses,
@@ -596,12 +619,12 @@ Projecting a lower-resolution ISH volume
 ----------------------------------------
 
 The ``ccf_streamlines`` packages also has functions for using the lower-resolution
-data from the `Allen Brain Atlas <http://mouse.brain-map.org>`_ of mouse
+data from the `Allen Brain Atlas <https://mouse.brain-map.org>`_ of mouse
 in situ hybridization (ISH) gene expression with its objects and functions.
 
 We can download an example coronal data set for the Pdyn gene with this link:
 
-http://api.brain-map.org/grid_data/download/71717084
+https://api.brain-map.org/grid_data/download/71717084
 
 After unzipping the downloaded file, there will be ``energy.mhd`` and ``energy.raw``
 files that contain the 3D gene expression information. You can use the ``SimpleITK``
@@ -648,4 +671,4 @@ Now we can project the data as before.
     :width: 800
 
 
-.. _whitepaper: http://help.brain-map.org/download/attachments/2818171/Conn_Informatics_Data_Processing.pdf?version=2&modificationDate=1507057121463&api=v2
+.. _whitepaper: https://s3.amazonaws.com/webflow-prod-assets/689cfbd308fa7373b604d290/68ee79702e0b8128cafcc5f5_Documentation_Mouse_Connectivity_Atlas-Mouse_CCF,_Reference_Atlas,_Version_3_(2017).pdf

docs/source/reference/processing.rst

@@ -2,7 +2,7 @@
 
 .. module:: ccf_streamlines.processing
 
-Utility Processing Functions (:mod:`ccf_streamlines.projection`)
+Utility Processing Functions (:mod:`ccf_streamlines.processing`)
 ================================================================
 
 Functions used to process original streamlines files into more consistent representations.