From ac6bf7bfc92ca28a002b60a81b31a4efb5f35d71 Mon Sep 17 00:00:00 2001 From: Nathan Gouwens Date: Mon, 31 Aug 2026 16:05:13 -0700 Subject: [PATCH] Restore the Read the Docs build and refresh the docs Read the Docs removed the ubuntu-20.04 build image on 2026-06-01, and .readthedocs.yaml had asked for it since 2022, so the hosted docs stop building before Sphinx runs. Move to ubuntu-24.04 on Python 3.12, which also needs newer docs pins: Sphinx 5.2.3 imports the imghdr module that Python 3.13 removed. The build does not install the package - conf.py mocks the third-party imports and scrapes the version out of pyproject.toml - so the interpreter here is independent of the requires-python floor. The build is warning-free against those pins, so turn on sphinx.fail_on_warning: a new warning means a cross-reference or an object name has drifted, and it should fail rather than land silently. Dropping html_static_path removes the one warning that stood in the way, since the tree keeps no _static directory. Content fixes found while checking the pages against the code: - The first Isocortex2dProjector example was missing a comma after hemisphere="both", so copying it raised a SyntaxError, and the coordinate projector example passed "flatmap_buttefly.h5". - The CCF white paper link 404ed into a forum category page. Repoint it at the 2017 technical white paper, confirmed to be the document the guide quotes and the source of the Figure 4 image. - Add an Installation section; the docs never said how to install the package or that the reference files come separately. - Upgrade the Allen download links to https, which they redirect to anyway, and fix three prose typos. Co-Authored-By: Claude Opus 5 --- .readthedocs.yaml | 16 ++++++++-- CLAUDE.md | 9 ++++-- docs/requirements.txt | 4 +-- docs/source/conf.py | 18 +++++++++-- docs/source/guide.rst | 47 +++++++++++++++++++++------- docs/source/reference/processing.rst | 2 +- 6 files changed, 73 insertions(+), 23 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 1b7690b..64bbc17 100644 --- a/.readthedocs.yaml +++ b/.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 \ No newline at end of file + - requirements: docs/requirements.txt diff --git a/CLAUDE.md b/CLAUDE.md index 3d46a12..ce66b3b 100644 --- a/CLAUDE.md +++ b/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`). diff --git a/docs/requirements.txt b/docs/requirements.txt index ad498d3..3ece85a 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 81fb045..9801d6b 100644 --- a/docs/source/conf.py +++ b/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", +} + diff --git a/docs/source/guide.rst b/docs/source/guide.rst index 3df21e8..a858cf3 100644 --- a/docs/source/guide.rst +++ b/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 `_ 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 `_ for the CCF. +`10-micron resolution average template data `_ 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 `_ +We'll use an `Allen Mouse Brain Connectivity Atlas `_ 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 `_ +We'll look at `this experiment `_ 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 `_ of mouse +data from the `Allen Brain Atlas `_ 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 diff --git a/docs/source/reference/processing.rst b/docs/source/reference/processing.rst index b4b8f20..d26df2a 100644 --- a/docs/source/reference/processing.rst +++ b/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.