docs: RTD hygiene — reconnect PyAutoFit RTD, converge conf.py, add docs CI

[Jammy2211]

Overview

A 2026-07-09 census of the docs/ReadTheDocs setup across PyAutoFit, PyAutoGalaxy and PyAutoLens found the RTD link broken in one place and fragile everywhere: pyautofit.readthedocs.io has not built since 2026-05-06 (its RTD project still points at rhayes777/PyAutoFit.git, so 16 docs commits — including the Jammy2211→PyAutoLabs URL audit #1265 and the Latent cookbook migration — never reached the live site), no repo builds docs in CI, and the three conf.py files have drifted (including a silent typo in PyAutoLens). This task is phase A of the docs-infrastructure middle path: fix the RTD wiring, delete dead configs, converge conf.py, and add a docs CI job to each repo. Phases B+C (shared PyAuto theming + a GitHub Pages hub) are parked in PyAutoMind/docs/libraries/docs_theming_and_hub.md and will be issued when this ships.

Run under --auto, effective level supervised (docs/medium caps at safe; the prompt header supervised binds — the RTD-dashboard legs need a human). Brain's sizing faculty scored this too-large (14) via the multi-repo heuristic and proposed a generic 4-phase split; overridden because the per-repo work is small and identical — the natural decomposition is one PR per repo within this task (calibration data point for the too-large heuristic).

Plan

• Human legs (RTD dashboard): reconnect the pyautofit RTD project to PyAutoLabs/PyAutoFit and confirm a fresh build goes live; update the pyautogalaxy/pyautolens RTD project repo URLs from Jammy2211/... to the PyAutoLabs org. Verified afterwards via the public RTD addons API (last-build date + repo URL).
• Delete dead configs: PyAutoFit/readthedocs.yml (drifted py3.11 duplicate), PyAutoGalaxy/readthedocs.yaml (duplicate), PyAutoFit/docs/requirements.txt (superseded by the pyproject [docs] extra RTD actually installs).
• Converge the three docs/conf.py on the Galaxy/Lens variant: fix the PyAutoLens nnumpydoc_class_members_toctree typo, remove the dead html_context blocks (github_version: "master", never read by Furo), bring PyAutoFit's autodoc/typehints config in line, fix or drop the phantom _static/pied-piper-admonition.css references in Fit and Lens.
• Add a docs CI job to each repo: build Sphinx HTML on PRs touching docs/, the package, or pyproject.toml; strict -W if the current warning baseline allows, otherwise fail on warning-count regression with the baseline recorded.
• Validate by building each repo's docs before/after locally, diffing warning counts, and spot-checking rendered API pages (the conf.py convergence changes real rendering in Fit and Lens).

Detailed implementation plan

Affected Repositories

• PyAutoFit (primary — dead RTD connection)
• PyAutoGalaxy
• PyAutoLens

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoFit	main	clean (0/0 vs origin)
./PyAutoGalaxy	main	clean (0/0 vs origin)
./PyAutoLens	main	clean (0/0 vs origin)

Suggested branch: feature/rtd-hygiene (worktrees under ~/Code/PyAutoLabs-wt/rtd-hygiene/)

Implementation Steps

1. PyAutoFit
   • Delete readthedocs.yml and docs/requirements.txt.
   • docs/conf.py: add sphinx_autodoc_typehints to extensions (already shipped in the [docs] extra but never enabled); adopt the Galaxy/Lens autodoc block (autodoc_default_options = {members, undoc-members, show-inheritance}, autodoc_class_signature = "separated", autoclass_content = "init", autosummary_imported_members = True, add_module_names = False, typehints settings); remove the dead html_context block; resolve html_static_path/pied-piper-admonition.css (create the asset or drop both references).
   • Before/after sphinx-build comparison — this changes real rendering of API pages (af.Model, af.Analysis spot-checks).
2. PyAutoGalaxy
   • Delete readthedocs.yaml.
   • docs/conf.py: remove the dead html_context block (reference variant otherwise).
3. PyAutoLens
   • docs/conf.py: fix nnumpydoc_class_members_toctree → numpydoc_class_members_toctree (verify the resulting toctree change renders sanely — the setting has been silently off); resolve the _static css reference; remove the dead html_context block.
4. All three — add .github/workflows/docs.yml: on PRs touching docs/**, the package dir, or pyproject.toml, run pip install .[docs] then sphinx-build -b html docs docs/_build; -W if the baseline is clean, else record the warning baseline and fail on regression. RTD's fail_on_warning stays false (CI owns strictness).
5. RTD dashboard (human) — reconnect/repoint the three RTD projects as above; verify with the addons API that a push to main triggers a fresh live build of pyautofit docs.

Key Files

• PyAutoFit/readthedocs.yml, PyAutoFit/docs/requirements.txt, PyAutoGalaxy/readthedocs.yaml — dead, delete
• PyAuto{Fit,Galaxy,Lens}/docs/conf.py — converge
• PyAuto{Fit,Galaxy,Lens}/.github/workflows/docs.yml — new CI job

Out of scope

• Theming + GitHub Pages hub (phases B+C, parked prompt docs/libraries/docs_theming_and_hub.md)
• plot.rst content rewrite (Remove all reference to sym link and the al_ files #592) and API-page staleness beyond what the CI warning baseline forces
• Migrating off ReadTheDocs; versioned/stable docs (only latest published — recorded as deliberate under nightly releases)

Original Prompt

Click to expand starting prompt

See PyAutoMind/issued/rtd_hygiene.md (moved from docs/libraries/rtd_hygiene.md) — carries the full census findings and the verbatim original request/decision record.

[Jammy2211]

Checkpoint (supervised run): PyAutoFit-leg routing question

While registering this task, the worktree conflict check found PyAutoFit is already claimed by two parked EP tasks (ep-diagnostics → feature/ep-diagnostics, ep-graphical-docs → feature/ep-graphical-docs, both awaiting-input). PyAutoGalaxy and PyAutoLens are unclaimed.

What the run is doing: proceeding now with the Galaxy + Lens legs (worktrees, conf.py fixes, dead-config deletion, docs CI) — these are unaffected by any answer below. The PyAutoFit leg is held (no worktree created), even though it's the repo with the dead RTD connection.

The fork — how to handle the PyAutoFit leg:

1. Wait for the EP claims to release (recommended): the Fit leg ships as its own PR once ep-diagnostics/ep-graphical-docs merge or release their worktrees. Zero merge-conflict risk; the cost is that the Fit conf.py/CI fixes wait on the EP queue.
2. Override the claim: the file sets are near-disjoint (this task: root readthedocs.yml, docs/conf.py, docs/requirements.txt, .github/workflows/docs.yml; EP docs task: graphical feature pages). If you say go, I create the Fit worktree alongside the EP ones and rebase whoever lands second.
3. Park the whole task until PyAutoFit is free (not recommended — Galaxy/Lens fixes and the RTD dashboard legs don't need to wait).

Independent of the answer: the RTD dashboard reconnection (pyautofit → PyAutoLabs/PyAutoFit, repoint galaxy/lens URLs) touches no repo worktree and can be done any time — that alone revives the dead pyautofit.readthedocs.io site, since the content fixes here are hygiene, not the outage cause.

Answering here resumes the held leg; the run continues on Galaxy + Lens meanwhile.

[Jammy2211]

Checkpoint (supervised run): ship sign-off + Heart YELLOW acknowledgement — Galaxy/Lens/Heart legs

Implementation of the Galaxy + Lens legs is complete and committed locally on feature/rtd-hygiene (nothing pushed). Scope notes vs the plan:

• PyAutoHeart was added to the task (worktree + branch): the repos define CI as thin callers into Heart's reusable workflows ("Heart owns all health/readiness checking" — main.yml), so the docs check is a Heart-owned reusable docs-build.yml mirroring lib-tests.yml mechanics (dep-chain source clones, sibling-branch aware), with thin docs.yml callers in each library. Strictly idiomatic, but it's one more repo than the plan named.
• Small riders: Sphinx build artifacts (docs/api/_autosummary, docs/api/generated, docs/_build) added to both .gitignores (my builds surfaced that they were never ignored); warning baselines recorded (docs/sphinx_warning_baseline.txt: Galaxy 105, Lens 134 — measured locally; may need a one-time CI recalibration, the workflow's error message documents the procedure).
• Verified: warning-set delta after the conf.py changes is exactly the removed phantom-_static warning (Lens 135→134, Galaxy 105→105); rendered pages text-identical; the Lens nnumpydoc typo fix is behavior-neutral (True is the numpydoc default, now explicit).

Gate status (four legs):

1. Tests: PyAutoGalaxy 962 passed · PyAutoLens 373 passed · PyAutoHeart 244 passed (full suites, worktree). Downstream dependents n/a — zero importable-code changes, no public API surface.
2. Smoke: n/a — docs/CI configuration only, no runtime script surface.
3. Review: surface generated (pyauto-brain review --task rtd-hygiene); verdict CLEAN — 3 commits, 10 files, no unintended content.
4. Heart: YELLOW — parks the ship because no reason set was acknowledged at launch. Reasons (exact list your ack would bind to, all pre-existing organism-scope, none from this branch):
   • workspace validation not passing (3 failed, 2026-07-09T09-48-30Z)
   • 58 stale parked script(s)
   • autolens_assistant: pinned BEHIND installed 2026.7.6.649
   • PyAutoMind: open PR 10d old

On your ack (reply here, e.g. "ack yellow, ship"): I push the three branches and open three pending-release PRs. Merge-order constraint: PyAutoHeart's PR must merge first — the Galaxy/Lens docs.yml callers reference docs-build.yml@main, so their new docs check errors until it lands (their PR bodies will say so).

Still open on this task: the PyAutoFit-leg routing question above, and the RTD dashboard human legs (reconnect pyautofit → PyAutoLabs; repoint galaxy/lens repo URLs) — the dashboard legs need no code and revive the dead pyautofit.readthedocs.io site on their own.

[Jammy2211]

Shipped (Galaxy/Lens/Heart legs) — PRs open, merge is yours

Human continued the run in-session (ship sign-off + Heart YELLOW ack, bound to the 4 reasons listed above). All three branches pushed, PRs open with pending-release:

Repo	PR	Suite
PyAutoHeart	#48 — reusable docs-build.yml	244 passed
PyAutoGalaxy	#495 — dead config, conf.py, docs CI	962 passed
PyAutoLens	#597 — typo, conf.py, docs CI	373 passed

Merge order: PyAutoHeart#48 first — the Galaxy/Lens docs checks reference docs-build.yml@main and error until it lands. After it merges, re-run/re-trigger the Galaxy/Lens docs checks; if the CI-measured warning count differs from the locally-measured baselines (105/134), recalibrate docs/sphinx_warning_baseline.txt once, with justification.

Workspace impact: none — API Changes are None in all three PRs (docs/CI configuration only); no workspace script references any touched file. Smoke n/a.

Remaining on this task:

1. RTD dashboard legs (human, ~5 min, do any time): at https://app.readthedocs.org/projects/pyautofit/ → Settings → connect the repository to PyAutoLabs/PyAutoFit (currently rhayes777/PyAutoFit.git, dead since 2026-05-06) and trigger a build of latest; same Settings check for pyautogalaxy/pyautolens (repoint Jammy2211/... → PyAutoLabs/...; their webhooks currently work, this is future-proofing). Verifiable afterwards via the addons API last-build timestamp.
2. PyAutoFit code leg: held pending the EP claims (human chose to continue on the recommendation = wait for ep-diagnostics/ep-graphical-docs to release PyAutoFit); its conf.py/dead-config/docs-CI fixes ship as a follow-up PR on this same issue.
3. After all legs merge: issue phases B+C (PyAutoMind/docs/libraries/docs_theming_and_hub.md — shared theming + GitHub Pages hub).

[Jammy2211]

Phase A complete (code side) — all four PRs merged 2026-07-09

PyAutoHeart#48 → PyAutoGalaxy#495 → PyAutoLens#597 → PyAutoFit#1342, merged in dependency order, human-authorized in-session. The docs CI check is now live on all three library repos and passed on first CI run in each (warning baselines 105/134/67 all held exactly — no recalibration needed). Worktrees removed, branches deleted.

The PyAutoFit leg went through under the human's claim override ("they don't clash") — disjointness against ep-diagnostics and ep-graphical-docs (PR #1334) was verified file-by-file before shipping; those tasks are unaffected.

Remaining on this issue: the RTD dashboard legs (human, deferred to 2026-07-10): reconnect pyautofit → PyAutoLabs/PyAutoFit (site dead since 2026-05-06) and repoint pyautogalaxy/pyautolens URLs to the org. Verification via the addons API will close this out.

Phases B+C (shared theming + GitHub Pages hub) are being issued now as their own task — phase A is shipped, so the parked prompt graduates.

[Jammy2211]

RTD dashboard legs complete — task done (2026-07-10)

Human completed the dashboard work this morning; verified via the public addons API:

Project	Repo URL	Last build
pyautofit	PyAutoLabs/PyAutoFit ✅	2026-07-10 07:05 ✅ (first since 2026-05-06)
pyautogalaxy	PyAutoLabs/PyAutoGalaxy ✅	2026-07-09 21:27 ✅
pyautolens	PyAutoLabs/PyAutoLens ✅	2026-07-09 21:28 ✅

The pyautofit outage root cause was confirmed as expected: the GitHub webhook survived the org transfer and kept firing, but RTD rejected deliveries (400) due to the old readthedocs.org payload host + missing secret, compounded by the stale rhayes777 repository URL. Fixed by updating the RTD repository URL, repointing the GitHub webhook to app.readthedocs.org with the integration secret, and redelivering. Webhook chain proven end-to-end.

Everything in this issue's scope is now shipped and verified. Follow-on work (shared theming + hub) lives on pyautolabs.github.io#1 (hub already live; theming PRs awaiting merge).