Extract howtofit into its own repository

[Jammy2211]

Overview

Move the HowToFit tutorial series out of autofit_workspace into a standalone
PyAutoLabs/HowToFit repository, mirroring the recent HowToLens extraction
(PyAutoLens PR #468 + autolens_workspace PRs, HowToLens bootstrap PR #1) and
HowToGalaxy extraction (PyAutoGalaxy PR #363 + autogalaxy_workspace PR #37,
HowToGalaxy bootstrap PR #1). Each lecture series becomes its own versioned,
tagged, independently-releasable repo rather than a subtree of the workspace,
and is now picked up automatically by /pre_build (see PyAutoBuild PR #53 which
registered HowToLens and HowToGalaxy).

Plan

• Scaffold a new PyAutoLabs/HowToFit repo with chapters 1-3 extracted out of
  autofit_workspace/scripts/howtofit and autofit_workspace/notebooks/howtofit
  (keep chapter_2_scientific_workflow as a deliberate empty stub, drop loose
  intro/plan text files). Tag matching the current workspace version.
• Delete howtofit/ from autofit_workspace and rewrite the 8 cross-references
  that still point into it (welcome.py, cookbooks, both READMEs, CLAUDE.md,
  top-level README).
• Update PyAutoFit library docs and paper to frame HowToFit as a standalone
  repo — 31 references across README, docs/howtofit/, docs/index.rst,
  docs/general/workspace.rst, paper/paper.md, and the docs/api/ cross-refs.
• Register HowToFit in PyAutoBuild alongside HowToLens and HowToGalaxy so
  /pre_build tags the new repo and bumps its Colab URLs on every release.

Detailed implementation plan

Affected Repositories

• autofit_workspace (primary — umbrella + sub-2)
• PyAutoLabs/HowToFit (new, sub-1 target)
• PyAutoFit (sub-3 target)
• PyAutoBuild (follow-up target)

Work Classification

Workspace (umbrella lives on autofit_workspace; sub-tasks fan out to the library and build repos later).

Branch Survey

Repository	Current Branch	Dirty?
./autofit_workspace	main	clean
./PyAutoFit	(not yet touched)	—
./PyAutoBuild	main	clean
PyAutoLabs/HowToFit	(does not exist yet)	—

Suggested branch (sub-1): feature/howtofit-bootstrap (on the new PyAutoLabs/HowToFit once created).
Worktree root: ~/Code/PyAutoLabs-wt/howtofit-bootstrap/

Starting state

• Jammy2211/HowToFit exists on GitHub but is empty (no default branch). Sub-1
  scaffolds PyAutoLabs/HowToFit directly — no transfer step.
• autofit_workspace/version.txt = 2026.4.13.6 (matches HowToLens/HowToGalaxy
  extraction tag).
• scripts/howtofit/ contents:
  • chapter_1_introduction/: start_here.py + 5 tutorials
  • chapter_2_scientific_workflow/: empty stub (README.rst + __init__.py)
  • chapter_3_graphical_models/: 8 tutorials (including two tutorial_optional_*)
  • Loose text files intro and plan (legacy planning notes)
• No cross-module simulator dependencies — sub-2 is a clean delete (unlike
  HowToGalaxy which had to relocate sersic.py back to scripts/imaging/).

Sub-task 1 — bootstrap PyAutoLabs/HowToFit

1. Create PyAutoLabs/HowToFit repo (public, empty init).
2. Copy autofit_workspace/scripts/howtofit/* → new repo scripts/ (drop the howtofit/ segment).
3. Copy autofit_workspace/notebooks/howtofit/* → new repo notebooks/.
4. Keep chapter_2_scientific_workflow/ stub; drop loose intro/plan.
5. Add workspace-like scaffolding: config/, root-level start_here.py, welcome.py,
   version.txt (2026.4.13.6), requirements.txt, runtime.txt, smoke_tests.txt,
   CLAUDE.md, README.rst, CITATIONS.rst, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE.
6. Rewrite in-tutorial Colab URLs from PyAutoLabs/autofit_workspace/blob/<old>/notebooks/howtofit/chapter_X/...
   to PyAutoLabs/HowToFit/blob/2026.4.13.6/notebooks/chapter_X/....
7. Tag 2026.4.13.6, push.

Sub-task 2 — remove howtofit from autofit_workspace

• Delete scripts/howtofit/ and notebooks/howtofit/.
• Update these files to point at the new repo:
  • welcome.py:79 (description bullet)
  • scripts/cookbooks/multiple_datasets.py:458 (URL link)
  • scripts/README.rst:6, notebooks/README.rst:6 (bullet)
  • CLAUDE.md:11 (file layout)
  • README.rst:15,46,65 (various prose + toctree-style links)
• Drop howtofit-specific entries from config/build/no_run.yaml,
  config/build/env_vars.yaml if present.
• New issue will be opened on autofit_workspace when sub-2 starts.

Sub-task 3 — update PyAutoFit library docs/URLs

Rewrite every howtofit URL across:

• README.rst
• docs/index.rst (toctree stays local; only link refs change)
• docs/howtofit/*.rst (4 pages — bulk-sed the Colab URLs)
• docs/general/workspace.rst
• paper/paper.md
• docs/api/{searches,plot,priors,samples,analysis,database,model}.rst (cross-refs)
• docs/cookbooks/multiple_datasets.rst
• docs/science_examples/astronomy.rst
• docs/overview/statistical_methods.rst
• docs/features/graphical.rst

Migration pattern:
PyAutoLabs/autofit_workspace/blob/<old>/notebooks/howtofit/chapter_X/tutorial_Y.ipynb
→ PyAutoLabs/HowToFit/blob/2026.4.13.6/notebooks/chapter_X/tutorial_Y.ipynb

New issue will be opened on PyAutoFit when sub-3 starts.

Follow-up — register HowToFit in PyAutoBuild

Piggybacks on PR #53 (HowToLens/HowToGalaxy registration). Add HowToFit/howtofit to:

• pre_build.sh
• .github/workflows/release.yml (find_scripts, generate_notebooks, run_scripts Configure, run_notebooks Configure, release_workspaces)
• autobuild/config/copy_files.yaml, autobuild/config/no_run.yaml
• autobuild/bump_colab_urls.sh regex
• CLAUDE.md workspace table + bump_colab_urls description

Can be a standalone PR or ride with sub-3.

Key Files

• autofit_workspace/scripts/howtofit/** — source material for sub-1, deleted in sub-2.
• autofit_workspace/welcome.py, README.rst, CLAUDE.md, scripts/README.rst, notebooks/README.rst, scripts/cookbooks/multiple_datasets.py — sub-2 prose updates.
• PyAutoFit/docs/howtofit/*.rst, PyAutoFit/README.rst, PyAutoFit/paper/paper.md, PyAutoFit/docs/**/*.rst — sub-3 URL rewrites.
• PyAutoBuild/pre_build.sh, .github/workflows/release.yml, autobuild/config/*.yaml, autobuild/bump_colab_urls.sh — follow-up registration.

Original Prompt

Click to expand starting prompt

$(cat /home/jammy/Code/PyAutoLabs/admin_jammy/prompt/autofit/howtofit.md)

[Jammy2211]

Sub-1 shipped — 2026-04-22

PR

• feat: bootstrap HowToFit repository (sub-1 of howtofit extraction) HowToFit#1 (merged)

What landed

Bootstrapped the new PyAutoLabs/HowToFit repo by transplanting autofit_workspace/scripts/howtofit/ (chapter_1_introduction + chapter_2 stub + chapter_3_graphical_models + simulators) into a standalone repo, mirroring the HowToLens/HowToGalaxy pattern. Includes root files, CI workflows (smoke_tests.yml, url_check.yml), and a PyAutoFit-only config tree.

Notable fix

Chapter 3 tutorials were silently broken against a fresh clone — they invoke simulators.py but the dataset_N/ families they need are produced by simulators_sample.py. Fixed by chain-running simulators_sample.py from the end of simulators.py via runpy. This bug was previously masked in autofit_workspace by committed sample datasets.

Pending sub-tasks

• sub-2: Remove howtofit/ from autofit_workspace + update its ~8 cross-references
• sub-3: Update PyAutoFit library docs + ~31 URL references across ~10 files
• pyautobuild-register: Register the howtofit build target in PyAutoBuild/autobuild/config/ so notebooks can be regenerated from scripts (parallel to the pending HowToLens/HowToGalaxy registration)

Session notes

• tutorial_5_results_and_samples.py is excluded from smoke tests via config/build/no_run.yaml with a NEEDS_FIX marker — it hits an IndexError in samples access, likely the InstanceInterpolator bug in autofit features/interpolate. Separate fix.
• autofit_workspace_developer/scripts/howtofit/chapter_1_introduction/tutorial_8_astronomy_example.py references were intentionally preserved — that script still lives in the developer repo.
• Local smoke: 10/10 pass under PYAUTO_TEST_MODE=2; CI smoke (3.12 + 3.13) + url_check: all green on PR Update fit.py #1.

[Jammy2211]

Sub-2 shipped — 2026-04-22

PR

• refactor: remove howtofit/ from autofit_workspace (sub-2 of howtofit extraction) #39 (merged)

What landed

Removed scripts/howtofit/ (38 files) and notebooks/howtofit/ (17 files) from autofit_workspace. Updated 8 cross-reference files to point at the new standalone repository:

• welcome.py, scripts/features/graphical_models.py, scripts/overview/overview_3_statistical_methods.py — prose + URL rewrites
• README.rst, scripts/README.rst, notebooks/README.rst, CLAUDE.md — structure/bullet/link updates
• config/build/no_run.yaml — dropped two now-orphaned skip entries

Smoke-tested locally (6/6 PASS); CI url_check green.

Still pending

• sub-3: Update PyAutoFit library docs (docs/howtofit/) + ~31 URL references to pyautofit.readthedocs.io/.../howtofit/... scattered across ~10 files. This is the remaining external blocker — until it ships, the readthedocs URLs in the PyAutoFit library still render the removed howtofit content. Deferred intentionally to keep sub-2's diff tight.
• pyautobuild-register: Register the howtofit build target in PyAutoBuild/autobuild/config/ so PyAutoLabs/HowToFit notebooks regenerate from scripts (parallel to the pending HowToLens/HowToGalaxy registration).

Notebook drift (minor, acceptable)

Three .ipynb files in autofit_workspace/notebooks/ still contain old HowToFit narrative text that mirrors the old .py prose: notebooks/features/graphical_models.ipynb, notebooks/cookbooks/multiple_datasets.ipynb, notebooks/overview/overview_3_statistical_methods.ipynb. These will self-heal on the next /pre_build run which regenerates all notebooks from their .py counterparts via PyAutoBuild's generate.py. Per the "never edit .ipynb directly" workspace rule.

[Jammy2211]

Sub-3 Shipped — 2026-04-22

PyAutoFit library-side updates for the HowToFit extraction are merged.

• PR: docs: remove howtofit/ tree and point tutorials to standalone repo PyAutoFit#1231 (MERGED)
• Issue: docs: remove howtofit/ tree and point tutorials to standalone repo PyAutoFit#1230

This removes the docs/howtofit/ chapter tree from the PyAutoFit readthedocs build and rewrites every lingering readthedocs.io/howtofit/… and autofit_workspace/…/howtofit/… URL to point at https://github.com/PyAutoLabs/HowToFit.

Status of the umbrella extraction

• sub-1: HowToFit scaffold (feat: bootstrap HowToFit repository (sub-1 of howtofit extraction) HowToFit#1 MERGED 2026-04-22)
• sub-2: remove howtofit/ from autofit_workspace + cross-refs (autofit_workspace#39 MERGED 2026-04-22)
• sub-3: update PyAutoFit library URLs + docs/howtofit/ (PyAutoFit#1231 MERGED 2026-04-22)
• pyautobuild-register: register howtofit build target in PyAutoBuild (pending)

Only the PyAutoBuild registration remains before the extraction is fully wrapped up.

[Jammy2211]

Umbrella Complete — 2026-04-22

Sub-4 (pyautobuild-register) is merged: PyAutoLabs/PyAutoBuild#55

Final state of the HowToFit extraction:

Sub	Scope	Status	PR
1	HowToFit scaffold (standalone repo)	MERGED	PyAutoLabs/HowToFit#1
2	Remove howtofit/ from autofit_workspace + cross-refs	MERGED	#39
3	Update PyAutoFit library URLs + docs/howtofit/	MERGED	PyAutoLabs/PyAutoFit#1231
4	Register howtofit build target in PyAutoBuild	MERGED	PyAutoLabs/PyAutoBuild#55

HowToFit now lives at https://github.com/PyAutoLabs/HowToFit and is built, tested, Colab-URL-bumped, and released by the same machinery that handles HowToGalaxy / HowToLens. Next release workflow run will emit HowToFit artefacts for the first time.

Closing this umbrella.