Restructure documentation according to Diataxis by gdevenyi · Pull Request #506 · CoBrALab/RABIES

gdevenyi · 2026-08-03T17:14:14Z

Reorganises docs/ into tutorials/, how_to/, reference/ and explanation/ so each page serves one user need, rather than mixing lesson, recipe, fact and discussion on the same page.

Builds clean under sphinx -n for both HTML and LaTeX, with zero broken links or unresolved cross-references (verified by walking every href in the built HTML).

Structure

docs/
├── tutorials/     first_run — new, there was none
├── how_to/        install · run_with_containers · select_scans (new) ·
│                  check_orientation · troubleshoot_registration ·
│                  assess_data_quality · optimise_confound_correction ·
│                  minimal_preprocessing · contribute
├── reference/     bids_inputs · cli · outputs · qc_outputs · metrics ·
│                  workflows (new) · bibliography
└── explanation/   preprocessing · confound_correction · analysis ·
                   data_quality · scan_diagnosis · distribution_plot ·
                   group_statistics

The significant splits:

A tutorial now exists. The docs previously offered no guided path from a fresh install to a first result — only an external workshop repo. tutorials/first_run.md walks the two-subject Zenodo example dataset through all three stages, with a QC inspection step in the middle.
running_the_software.md was tutorial, reference and how-to at once → reference/bids_inputs.md, reference/cli.md, how_to/run_with_containers.md.
analysis_QC.md mixed the "why" with the procedure → explanation/data_quality.md keeps the concepts, how_to/assess_data_quality.md takes generating the reports, setting thresholds and reporting in a publication.
Source docstrings inlined in the preprocessing and confound correction pages → reference/workflows.md.
how_to/select_scans.md is new: --bids_filter, --inclusion_ids and --exclusion_ids were previously only described in --help.

All 20 MyST anchors are preserved, so incoming links still resolve.

Documentation errors fixed against the code

Documented	Actual
`--conf_prior_idx` / `--bold_prior_idx`	`--prior_confound_idx` / `--prior_bold_idx`
`--scan_QC_thresholds` described loosely	takes a dict expression, e.g. `'{DR:{Dice:[0.3],Conf:[0.25],Amp:false}}'`
QC folders `Native2Unbiased/`, `Unbiased2Atlas/`	`commonspace_reg_wf.Anat2Unbiased/`, `commonspace_reg_wf.Unbiased2Atlas/`, or `commonspace_reg_wf.Anat2Atlas/` under `fast_commonspace=true` (undocumented)
`analysis_datasink/`	`commonspace_analysis_datasink/` / `nativespace_analysis_datasink/`
`--conf_list`, `--detrending`	`--nuisance_regressors` (the former is deprecated and raises), `--detrending_order`
Docker example pulled `gabdesgreg/rabies`	installation page says `ghcr.io/cobralab/rabies`

Sphinx configuration

html_theme was 'groundwork', which is not installed and was silently overridden by sphinx_rtd_dark_mode. Set explicitly to sphinx_rtd_theme.
html_theme_options was defined twice; the second clobbered the first, cutting navigation_depth from 3 to 2.
Pinned docutils==0.17.1 — sphinx==5.0, myst-parser and sphinxcontrib-bibtex have no other version in common, so the resolver could pick a broken combination.
Added sphinx-design (pinned <0.6 to respect the sphinx==5.0 pin) and sphinx-copybutton, plus colon_fence/deflist MyST extensions, heading anchors, and numfig.

Formatting

<details> HTML → {dropdown}. A raw <!DOCTYPE html> tree dump embedded mid-page → a captioned code block (which also fixes it for the PDF build). Apptainer/Docker → {tab-set}. Images → {figure} with alt text and numbering. Parameter lists → definition lists. Admonitions throughout.

Reviewer note

The tutorial's "expect it to run for an hour or more" for the preprocessing step is an order-of-magnitude estimate — I have not run the example dataset end to end. Worth a sanity check from someone who has.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Kdq57U3c4xpcRTXWhtpWrt

Reorganise docs/ into tutorials/, how_to/, reference/ and explanation/, so each page serves one user need instead of mixing lesson, recipe, fact and discussion on the same page. Structural changes: - Add a tutorial (docs/tutorials/first_run.md). There was none: the docs offered no guided path from a fresh install to a first result. - Split running_the_software.md, which was tutorial, reference and how-to at once, into reference/bids_inputs.md, reference/cli.md and how_to/run_with_containers.md. - Split analysis_QC.md into explanation/data_quality.md (what the reports are and why) and how_to/assess_data_quality.md (generating them, setting thresholds, reporting in a publication). - Move the source docstrings inlined in the preprocessing and confound correction pages into reference/workflows.md. - Add how_to/select_scans.md, covering --bids_filter, --inclusion_ids and --exclusion_ids, which were previously only described in --help. - Promote the single-entry FAQ to a titled how-to guide. All MyST cross-reference anchors are preserved, so incoming links still resolve. Documentation errors fixed against the code: - --conf_prior_idx/--bold_prior_idx do not exist; the options are --prior_confound_idx/--prior_bold_idx. - --scan_QC_thresholds takes a dictionary expression; document its actual syntax and keys. - QC report folders are commonspace_reg_wf.Anat2Unbiased/, commonspace_reg_wf.Unbiased2Atlas/ and commonspace_reg_wf.Anat2Atlas/ (with fast_commonspace=true), not Native2Unbiased/ and Unbiased2Atlas/. The fast_commonspace layout was undocumented. - Analysis outputs land in commonspace_analysis_datasink/ or nativespace_analysis_datasink/, not analysis_datasink/. - --conf_list is deprecated and raises; --detrending is --detrending_order. - The Docker example pulled gabdesgreg/rabies while the installation page pointed at ghcr.io/cobralab/rabies. Sphinx configuration: - html_theme was set to 'groundwork', which is not installed and was silently overridden by sphinx_rtd_dark_mode. Set it to sphinx_rtd_theme explicitly. - html_theme_options was defined twice; the second definition clobbered the first, reducing navigation_depth from 3 to 2. - Pin docutils==0.17.1. sphinx 5.0, myst-parser and sphinxcontrib-bibtex have no other version in common, so the resolver could pick a broken combination. - Add sphinx-design (pinned <0.6 for the sphinx==5.0 pin) and sphinx-copybutton, plus colon_fence/deflist MyST extensions, heading anchors, and numfig. Formatting: <details> blocks become {dropdown}; a raw <!DOCTYPE html> tree dump becomes a captioned code block; Apptainer and Docker instructions become a {tab-set}; images become {figure} with alt text; parameter lists become definition lists. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kdq57U3c4xpcRTXWhtpWrt

Copilot

🟡 Not ready to approve

Doc build dependencies in docs/requirements.txt still leave key Sphinx/MyST extensions unpinned, which risks RTD/CI breakage and non-reproducible builds given the pinned older Sphinx/docutils stack.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

This PR restructures the Sphinx/MyST documentation into a Diátaxis-style layout (tutorials / how-to guides / reference / explanation), aiming to make each page serve a single user need while preserving anchors and improving Sphinx build reliability.

Changes:

Reorganized and rewrote docs into docs/tutorials/, docs/how_to/, docs/reference/, and docs/explanation/, replacing several legacy top-level pages.
Added a new “first run” tutorial and expanded task-focused guides (containers, scan selection, QA/QC workflows, minimal preprocessing).
Updated Sphinx configuration and doc build requirements (theme, MyST extensions, additional Sphinx extensions, CSS).

File summaries

File	Description
docs/tutorials/index.md	Adds tutorials landing page and toctree for the tutorial section.
docs/tutorials/first_run.md	New end-to-end “first run” tutorial covering container install → preprocessing → QC → confound correction → analysis.
docs/troubleshooting.md	Removes legacy troubleshooting page (content moved into focused how-to/reference pages).
docs/running_the_software.md	Removes legacy mixed-mode “running the software” page (split across reference/how-to/tutorial).
docs/requirements.txt	Updates doc build dependencies (Sphinx extensions, docutils pin, theme tooling).
docs/reference/workflows.md	New workflow reference page using `literalinclude` snippets from source docstrings.
docs/reference/qc_outputs.md	New reference describing preprocessing QC report folders and meaning.
docs/reference/outputs.md	New reference enumerating outputs/datasinks across stages, with QC/diagnosis outputs.
docs/reference/metrics.md	New detailed metric definitions page (anchors preserved/expanded).
docs/reference/index.md	New reference section index with toctrees for running/output/internal references.
docs/reference/cli.md	New CLI reference page with generated `--help` output and worked examples.
docs/reference/bids_inputs.md	New input requirements page (BIDS structure, filters, orientation, example dataset).
docs/reference/bibliography.md	New bibliography page using MyST bibliography directive.
docs/preprocessing.md	Removes legacy preprocessing page (replaced by explanation + workflows reference).
docs/preproc_QC.md	Removes legacy preprocessing QC page (replaced by `reference/qc_outputs.md`).
docs/outputs.md	Removes legacy outputs page (replaced by `reference/outputs.md`).
docs/nested_docs/scan_diagnosis.md	Removes legacy nested scan diagnosis page (replaced by `explanation/scan_diagnosis.md`).
docs/nested_docs/registration_troubleshoot.md	Removes legacy nested registration troubleshooting (replaced by `how_to/troubleshoot_registration.md`).
docs/nested_docs/optim_CR.md	Removes legacy nested confound-optimization page (replaced by `how_to/optimise_confound_correction.md`).
docs/nested_docs/group_stats.md	Removes legacy nested group stats page (replaced by `explanation/group_statistics.md`).
docs/nested_docs/distribution_plot.md	Removes legacy nested distribution plot page (replaced by `explanation/distribution_plot.md`).
docs/metrics.md	Removes legacy metrics page (replaced by `reference/metrics.md`).
docs/installation.md	Removes legacy installation page (replaced by `how_to/install.md`).
docs/index.md	Updates documentation landing page with Diátaxis navigation tiles + section toctrees.
docs/how_to/troubleshoot_registration.md	New how-to for diagnosing registration failures and mapping them to parameters.
docs/how_to/select_scans.md	New how-to for `--bids_filter`, `--inclusion_ids`, `--exclusion_ids`, and QC-driven exclusion.
docs/how_to/run_with_containers.md	New how-to explaining bind-mount rules and providing Apptainer/Docker examples.
docs/how_to/optimise_confound_correction.md	New how-to protocol for iteratively improving confound correction using QC reports.
docs/how_to/minimal_preprocessing.md	New how-to for “SHAM preprocessing” to support already-preprocessed inputs.
docs/how_to/install.md	New installation guide (container / PyPI / Neurodesk) with updated registry references.
docs/how_to/index.md	New how-to section index organizing guides by goal area.
docs/how_to/contribute.md	New contributor guide (dev setup, PR steps, debugging, extending Nipype workflows).
docs/how_to/check_orientation.md	New how-to for validating NIfTI orientation (RAS+) via ITK-SNAP.
docs/how_to/assess_data_quality.md	New how-to for generating/interpreting diagnosis reports and reporting QC in publications.
docs/faq.md	Removes legacy FAQ (key content moved into dedicated how-to pages).
docs/explanation/scan_diagnosis.md	New explanation of the spatiotemporal diagnosis report and key markers.
docs/explanation/preprocessing.md	New explanation of preprocessing workflow and rationale, linking into workflow reference.
docs/explanation/index.md	New explanation section index + toctrees for processing and data quality topics.
docs/explanation/group_statistics.md	New explanation of group statistical QC report and interpretation constraints.
docs/explanation/distribution_plot.md	New explanation of distribution plot purpose and reading thresholds/outliers.
docs/explanation/data_quality.md	New high-level explanation of the QC framework and why the three report levels exist.
docs/explanation/confound_correction.md	New explanation of confound correction pipeline steps and math/assumptions.
docs/explanation/analysis.md	New explanation of connectivity analyses (seed/matrix/ICA/dual regression).
docs/contributing.md	Removes legacy contributing page (replaced by `how_to/contribute.md`).
docs/confound_correction.md	Removes legacy confound correction page (replaced by `explanation/confound_correction.md`).
docs/conf.py	Updates Sphinx config (theme, extensions, MyST extensions/anchors, numfig, copybutton).
docs/bibliography.md	Removes legacy bibliography page (replaced by `reference/bibliography.md`).
docs/analysis.md	Removes legacy analysis page (replaced by `explanation/analysis.md`).
docs/analysis_QC.md	Removes legacy analysis QC page (replaced by `explanation/*` + `how_to/assess_data_quality.md`).
docs/_static/custom.css	Adds RTD theme CSS tweaks for width, scroll behavior, and definition list readability.
.gitignore	Adds ignores for `docs/_build/` and `__pycache__/`.

Review details

Files reviewed: 50/51 changed files
Comments generated: 1
Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

 myst-parser
 sphinx-rtd-dark-mode
 sphinx-rtd-theme
+sphinx-design<0.6  # 0.6+ requires sphinx>=6
+sphinx-copybutton


gdevenyi · 2026-08-03T17:31:22Z

A rendered version of this PR is available at
https://rabies--506.org.readthedocs.build/en/506/

`collapse_navigation: False` already made Sphinx emit the complete toctree into every page, but the RTD theme still hid most of it in CSS, so the nav only opened along the branch you were currently on (readthedocs/sphinx_rtd_theme#455). Override the three theme rules that do the hiding, and drop the disclosure arrows, which now have nothing to toggle. This exposes a latent theme bug: nested entries are painted #404040, which only works because the theme never shows them off the current branch. Once every branch is open, off-branch entries sit on the dark sidebar and that colour is illegible. Give them the same light-on-dark treatment as the top-level entries, and put the dark text back on the current branch, where the background really is light. Verified in headless Chrome against computed styles: all 45 nav entries visible, no collapsed lists, no visible arrows, and legible contrast in both light and dark mode. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kdq57U3c4xpcRTXWhtpWrt

Move the whole docs stack forward and drop the pins that were only holding it back: sphinx 5.0 -> 9.1.0 myst-parser 1.0.0 -> 5.1.0 sphinx-rtd-theme 2.0.0 -> 3.1.0 sphinxcontrib-bibtex 2.6.5 -> 2.7.0 sphinx-design 0.5.0 -> 0.7.0 docutils 0.17.1 -> 0.22.4 The docutils==0.17.1 and sphinx-design<0.6 pins existed only to satisfy sphinx==5.0, so both are gone. Upper bounds are now specified only where a real incompatibility exists, so routine upgrades no longer need a change here. Bump Read the Docs to ubuntu-24.04 and Python 3.12. 3.12 is the ceiling, not a preference: docs/requirements.txt installs rabies so that sphinxcontrib-programoutput can run `rabies --help` at build time, and rabies declares python_requires <3.13. The upgrade surfaced a latent cross-reference bug. Seven page anchors sat immediately after their H1, so they targeted the following paragraph or figure rather than the section, and had no title for `:ref:` to use as link text. Sphinx 5 rendered that silently; newer myst-parser reports it. Moving each anchor above its heading makes it a section target, which is what every incoming link already meant. Verified with the upgraded stack: HTML and LaTeX both build clean under -n, zero broken links or unresolved cross-references, sphinx-design cards, tabs and dropdowns all render, and the expanded-sidebar CSS still applies correctly under RTD theme 3.1 (45 entries, none collapsed, contrast intact). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kdq57U3c4xpcRTXWhtpWrt

…everal outdated aspects of the documentation were also corrected. The tutorial section still need revising.

… parameters.

…d the test dataset, addition of actual QC reports generated through the tutorial, and brief coverage of the --data_diagnosis outputs.

Gab-D-G · 2026-09-02T18:34:49Z

I am done providing full revision of the documentation. It would be good to merge as far as I'm concerned, but perhaps we can request a final AI check for types/format mistakes?

- Replace the unknown {Advice} directive with {tip} and nest it under list item 1 so the protocol renders as one list - Restore the 3D_EPI_target anchor that metrics.md links to - Use the actual flag names --detrending and --read_datasink - Add the blank line that kept the README analysis paragraph out of the preceding bullet list - Update the link text for the renamed container syntax page - Correct spelling and grammar slips, and normalise to British spelling Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JbjzuSab2kesaLAq9wbw2B

Resolve .gitignore by taking master's version, which is a superset of the ignore rules added on this branch. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JbjzuSab2kesaLAq9wbw2B

gdevenyi · 2026-09-03T01:57:29Z

Small typo and formatting pass done, ready for merge on @Gab-D-G approval

Gab-D-G · 2026-09-03T09:37:52Z

Alright all good on my end now, I'll merge now.

Copilot AI review requested due to automatic review settings August 3, 2026 17:14

Copilot started reviewing on behalf of gdevenyi August 3, 2026 17:14 View session

gdevenyi requested review from CMonnin and Gab-D-G August 3, 2026 17:16

Copilot AI reviewed Aug 3, 2026

View reviewed changes

Comment thread docs/requirements.txt

Comment on lines 6 to +10

myst-parser

sphinx-rtd-dark-mode

sphinx-rtd-theme

sphinx-design<0.6 # 0.6+ requires sphinx>=6

sphinx-copybutton

gdevenyi and others added 6 commits August 3, 2026 13:39

Complete proof-reading of AI revisions on new documentation layout. S…

2d54be1

…everal outdated aspects of the documentation were also corrected. The tutorial section still need revising.

Documentation of the default template, and how to change the template…

6502f80

… parameters.

change_template.md needs referencing in the index

cefa135

Reworking of the tutorial for compatibility with original tutorial an…

a39c4a8

…d the test dataset, addition of actual QC reports generated through the tutorial, and brief coverage of the --data_diagnosis outputs.

gdevenyi and others added 2 commits September 2, 2026 21:47

replace 3D_EPI_target link for wf_bold_ref link.

26170c8

Gab-D-G merged commit 8950894 into master Sep 3, 2026
3 checks passed

Gab-D-G deleted the docs/diataxis-restructure branch September 3, 2026 09:41

Navigation Menu

Uh oh!

Restructure documentation according to Diataxis - #506

Restructure documentation according to Diataxis#506
Gab-D-G merged 10 commits into
masterfrom
docs/diataxis-restructure

gdevenyi commented Aug 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

gdevenyi commented Aug 3, 2026

Uh oh!

Gab-D-G commented Sep 2, 2026

Uh oh!

gdevenyi commented Sep 3, 2026

Uh oh!

Gab-D-G commented Sep 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

gdevenyi commented Aug 3, 2026

Structure

Documentation errors fixed against the code

Sphinx configuration

Formatting

Reviewer note

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Not ready to approve

Uh oh!

gdevenyi commented Aug 3, 2026

Uh oh!

Gab-D-G commented Sep 2, 2026

Uh oh!

gdevenyi commented Sep 3, 2026

Uh oh!

Gab-D-G commented Sep 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants