docs: batch-job base-image rebuild workflow + fix Sphinx docstring warnings#141
Merged
Merged
Conversation
…rnings Add a `scripts/build_base_image.sh` helper and document the build-and-push-on-submit workflow used when SpikeLab source has changed locally. The shared `analysis-base` image is a frozen snapshot of the source at build time, so the running container can silently diverge from a developer's local code. The new subsection in `batch_jobs/INSTRUCTIONS.md` (mirrored in `docs/source/guides/batch_jobs.rst`) walks through rebuilding under a developer-scoped tag and passing it via `--image`. Adds a preflight bullet to the Fixed Workflow that triggers off `git status` of `src/spikelab/`. Also clears 9 pre-existing Sphinx warnings in source docstrings: - plot_utils.py: rewrite Returns dicts in plot_prediction_probability_heatmap and plot_responsive_unit_map to avoid multi-line inline literals - stim_sorting/pipeline.py, recentering.py, spikedata/spikeslicestack.py: add blank line before nested bullet lists so RST recognises them - stim_sorting/preprocess.py: add TYPE_CHECKING import for BaseRecording so sphinx_autodoc_typehints can resolve the return annotation (spikeinterface remains an optional runtime dependency) No runtime behaviour changes. All 5 edited Python files pass black --check.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two unrelated docs/typing improvements bundled into one PR:
Batch-job base-image rebuild workflow. The shared
ghcr.io/braingeneers/spikelab-analysis-base:cpu/:gpuimages are frozen snapshots ofsrc/spikelab/at build time — they do not auto-update when the library source changes. This caused silent staleness when a developer iterated on a feature branch and submitted a batch job: the running container exposed an older API than the local script was written against.scripts/build_base_image.shhelper, mirroring the existingbuild_temp_image.sh(build only, printsBUILT_IMAGE=<tag>, no auto-push).src/spikelab/batch_jobs/INSTRUCTIONS.mddocumenting the developer-scoped tag pattern (${USER}-<git-sha>) and how to pass it via--image.git statusofsrc/spikelab/.docs/source/guides/batch_jobs.rstso the public docs stay consistent.Sphinx docstring warnings. Clears 9 warnings that surfaced when building the docs with
-W:spikedata/plot_utils.py: rewrite the Returns dicts inplot_prediction_probability_heatmapandplot_responsive_unit_mapto avoid multi-linespike_sorting/stim_sorting/pipeline.py,recentering.py,spikedata/spikeslicestack.py: add a blank line before nested bullet lists so RST recognises them instead of treating them as block quotes.spike_sorting/stim_sorting/preprocess.py: add aTYPE_CHECKINGimport forBaseRecordingsosphinx_autodoc_typehintscan resolve theTuple["BaseRecording", dict]return annotation.spikeinterfaceremains an optional runtime dependency (lazy import inside the function body is unchanged).No runtime behaviour changes.
black --checkclean on all 5 edited Python files. Full test suite passes locally (exit 0).Test plan
-Wno longer emits the 9 warnings these changes targetbash scripts/build_base_image.sh cpu spikelab/analysis-base:cpubuilds successfully (smoke test — does not need to be run by reviewer)