Skip to content

Fix README: broken docs-build command, broken link, typos, stale content - #410

Open
animmosmith wants to merge 4 commits into
407-scaled-circular-montagefrom
409-readme-audit-fixes
Open

Fix README: broken docs-build command, broken link, typos, stale content#410
animmosmith wants to merge 4 commits into
407-scaled-circular-montagefrom
409-readme-audit-fixes

Conversation

@animmosmith

Copy link
Copy Markdown
Collaborator

Summary

Fixes #409.

  • "Build docs locally" was broken outright - verified by actually running it: the documented sphinx-apidoc -f -o docs/source docs/build --separate fails immediately since neither docs/source nor docs/build exist. Cross-checked .readthedocs.yaml (which builds via docs/conf.py directly) and confirmed the correct, working command is a single sphinx-build -b html docs/ docs/_build/html - no separate apidoc step needed, since sphinx.ext.autosummary (already configured in docs/conf.py) generates the API docs automatically.
  • Fixed a broken markdown link ((uv)[url][uv](url)) and a Windows-style backslash path inside a bash command block.
  • Fixed typos (regester, monatge, complie, awarenes, plesant, aknowledged) and inconsistent "PyOpia"/"PyOPIA" naming throughout.
  • Replaced the "Development targets" section - stale, and in places directly contradicting the current architecture (e.g. it said "no use of settings/config files," but the whole Pipeline is config-driven) - with a short, accurate "Design principles" section.
  • Clarified step 5's montage.png as an output file rather than a command, and noted that init-project --example-data both downloads images and generates config.toml, so it doesn't appear to come from nowhere.
  • Expanded the Docker rationale beyond "for users who prefer not to install dependencies directly" (reproducibility, avoiding heavy ML dependency installs, consistent behaviour across OS, HPC/server use).

Test plan

  • Ran the full quick-start flow end-to-end with real example data: init-project --example-dataprocessmerge-mfdatamake-montage (including the corrected forward-slash path) → confirmed montage.png is produced
  • Ran the corrected "Build docs locally" command and confirmed it actually builds

🤖 Generated with Claude Code

@animmosmith animmosmith added documentation Improvements or additions to documentation priority-medium labels Jul 31, 2026
@animmosmith animmosmith self-assigned this Jul 31, 2026
animmosmith added a commit that referenced this pull request Jul 31, 2026
README's "Build docs locally" section now syncs the docs dependency group
via uv before building, matching the RTD config. Bumped version to 2.16.20
so this PR is ready to merge right after #394, #404, #406, #408, #410.
@animmosmith
animmosmith requested a review from emlynjdavies July 31, 2026 14:47
@animmosmith
animmosmith changed the base branch from main to 407-scaled-circular-montage July 31, 2026 17:00
animmosmith and others added 2 commits August 5, 2026 11:07
Fixes #409.

- "Build docs locally" was broken outright: the documented sphinx-apidoc
  command referenced docs/source and docs/build, neither of which exist.
  Verified against .readthedocs.yaml and confirmed the correct, working
  command is a single sphinx-build call (sphinx.ext.autosummary, already
  configured in docs/conf.py, generates the API docs automatically).
- Fixed a broken markdown link (brackets/parens were swapped) and a
  Windows-style backslash path inside a bash command.
- Fixed typos (regester, monatge, complie, awarenes, plesant, aknowledged)
  and inconsistent "PyOpia"/"PyOPIA" naming throughout.
- Replaced the "Development targets" section, which had become stale and
  in places directly contradicted the current architecture (e.g. it said
  "no use of settings/config files," but the whole pipeline is config-driven),
  with a short, accurate "Design principles" section.
- Clarified step 5's montage.png as an output file, not a command, and
  noted that init-project --example-data both downloads images and
  generates config.toml, so it doesn't appear to come from nowhere.
- Expanded the Docker rationale beyond "for users who prefer not to install
  dependencies directly."

Verified the full quick-start flow (init-project, process, merge-mfdata,
make-montage) end-to-end with real example data.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@animmosmith
animmosmith force-pushed the 409-readme-audit-fixes branch from e52e87a to fbade52 Compare August 5, 2026 10:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation priority-medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README audit: broken docs-build instructions, typos, stale dev targets

1 participant