docs: remove howtofit/ tree and point tutorials to standalone repo

[Jammy2211]

Overview

This is sub-task 3 of the HowToFit extraction (issue #38 on autofit_workspace). Sub-1 created the standalone PyAutoLabs/HowToFit repo (PR merged). Sub-2 removed the howtofit/ tree from autofit_workspace and rewrote its cross-references (PR merged). This sub-task updates PyAutoFit — library docs and prose — so the tutorial references no longer point at a non-existent pyautofit.readthedocs.io/howtofit/ path or at Jammy2211/autofit_workspace/.../howtofit/, and instead point at the new standalone PyAutoLabs/HowToFit repo.

Plan

• Delete the docs/howtofit/ Sphinx chapter tree (4 .rst files) — these chapters now live in the standalone HowToFit repo, not inside PyAutoFit's readthedocs
• Remove the matching Tutorials toctree entries from docs/index.rst
• Rewrite every pyautofit.readthedocs.io/.../howtofit/... URL and every autofit_workspace/.../howtofit/... URL to point at github.com/PyAutoLabs/HowToFit, following the URL-rewrite scheme established in sub-2
• Rewrite the HowToFit prose sections in docs/general/workspace.rst and README.rst from "part of the workspace" framing to "standalone tutorial repo" framing
• Update the three HowToFit references in paper/paper.md (JOSS paper prose) — URLs and framing only, no scientific content changes
• Verify with grep -rn howtofit PyAutoFit --include='*.rst' --include='*.md' --exclude-dir=build (zero matches expected) and a clean Sphinx build

Detailed implementation plan

Affected Repositories

• PyAutoFit (primary, sole)

Work Classification

Library (docs and prose only — no Python code changes)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoFit	main	clean

Suggested branch: feature/howtofit-docs-update
Worktree root: ~/Code/PyAutoLabs-wt/howtofit-docs-update/ (created later by /start_library)

URL rewrite scheme

• pyautofit.readthedocs.io/en/latest/howtofit/howtofit.html → github.com/PyAutoLabs/HowToFit
• pyautofit.readthedocs.io/en/latest/howtofit/chapter_1_introduction.html → github.com/PyAutoLabs/HowToFit/blob/main/notebooks/chapter_1_introduction/
• github.com/Jammy2211/autofit_workspace/.../howtofit/chapter_graphical_models/tutorial_4_hierachical_models.ipynb → github.com/PyAutoLabs/HowToFit/blob/main/notebooks/chapter_3_graphical_models/tutorial_4_hierachical_models.ipynb

Implementation Steps

1. Delete docs/howtofit/ directory and its 4 files (howtofit.rst, chapter_1_introduction.rst, chapter_2_scientific_workflow.rst, chapter_3_graphical_models.rst)
2. Edit docs/index.rst lines 197-205: remove the four howtofit/... toctree lines. If the :caption: Tutorials: block becomes empty, remove the whole block.
3. Rewrite the HowToFit: introduction chapter link line in the 7 API .rst files (model.rst, plot.rst, priors.rst, analysis.rst, database.rst, searches.rst, samples.rst) to point at github.com/PyAutoLabs/HowToFit (or the appropriate chapter folder).
4. Rewrite docs/general/workspace.rst lines 16-24 (HowToFit section) in the sub-2 pointer style — HowToFit is a standalone repo now.
5. Rewrite docs/features/graphical.rst (2 refs) to point at notebooks/chapter_3_graphical_models/.
6. Rewrite docs/overview/statistical_methods.rst:30 URL to the PyAutoLabs/HowToFit GitHub path.
7. Rewrite docs/cookbooks/multiple_datasets.rst and docs/science_examples/astronomy.rst readthedocs URLs.
8. Rewrite the 3 README.rst references (header link, autofit_workspace+HowToFit sentence, readthedocs HowToFit overview line).
9. Rewrite the 3 paper/paper.md HowToFit references — URLs and framing only; do not alter scientific prose.
10. Verify: grep -rn howtofit PyAutoFit --include='*.rst' --include='*.md' --exclude-dir=build returns zero matches. Run cd docs && make html and confirm no new broken-reference warnings.

Key Files

• docs/howtofit/*.rst — delete
• docs/index.rst — toctree entries removed
• docs/api/{model,plot,priors,analysis,database,searches,samples}.rst — API cross-ref link rewrite
• docs/general/workspace.rst — HowToFit section rewrite
• docs/features/graphical.rst, docs/overview/statistical_methods.rst, docs/cookbooks/multiple_datasets.rst, docs/science_examples/astronomy.rst — URL rewrites
• README.rst — 3 references
• paper/paper.md — 3 references in JOSS paper prose

Out of scope

• build/lib/howtofit/ (generated Sphinx output, self-heals on next build)
• Registering the howtofit target in PyAutoBuild (separate follow-up on issue Aggregator With Tag #38)
• Any further workspace or HowToFit-repo changes (done in sub-1 and sub-2)

Original Prompt

Click to expand starting prompt

PyAutoFit library updates for HowToFit extraction (sub-3 of issue #38)

Sub-1 and sub-2 of the HowToFit extraction have shipped:

• Sub-1: PyAutoLabs/HowToFit standalone repo exists (PR Overwriting a prior over-writes the upper / lower limits and resets them to +/- inf #1 merged)
• Sub-2: howtofit/ tree removed from autofit_workspace (PR Issue linking galaxies as constants through hyper phases #39 merged)

This sub-task updates @PyAutoFit — library docs and prose — so the tutorial references no longer
point into autofit_workspace/howtofit/ or pyautofit.readthedocs.io/howtofit/, and instead point to
the new standalone PyAutoLabs/HowToFit GitHub repo.

URL rewrite scheme

There is no pyautofit.readthedocs.io/howtofit/... anymore — those chapter pages will be deleted. For
every old readthedocs link and every Jammy2211/autofit_workspace/.../howtofit/... link, rewrite to
the HowToFit GitHub repo's notebooks:

• Old: https://pyautofit.readthedocs.io/en/latest/howtofit/chapter_1_introduction.html
  New: https://github.com/PyAutoLabs/HowToFit/blob/main/notebooks/chapter_1_introduction/ (or landing page)
• Old: https://pyautofit.readthedocs.io/en/latest/howtofit/howtofit.html
  New: https://github.com/PyAutoLabs/HowToFit
• Old: https://github.com/Jammy2211/autofit_workspace/.../howtofit/chapter_graphical_models/tutorial_4_hierachical_models.ipynb
  New: https://github.com/PyAutoLabs/HowToFit/blob/main/notebooks/chapter_3_graphical_models/tutorial_4_hierachical_models.ipynb

Scope

1. Delete the docs/howtofit/ tree

Remove these four files:

• @PyAutoFit/docs/howtofit/howtofit.rst
• @PyAutoFit/docs/howtofit/chapter_1_introduction.rst
• @PyAutoFit/docs/howtofit/chapter_2_scientific_workflow.rst
• @PyAutoFit/docs/howtofit/chapter_3_graphical_models.rst

And the now-empty docs/howtofit/ directory itself.

2. docs/index.rst toctree

Lines ~202-205 contain the Tutorials toctree entries for the HowToFit chapters. Remove those four
toctree lines. If the :caption: Tutorials: toctree becomes empty as a result, remove the whole
toctree block (including the caption header).

3. API doc cross-references

Seven API .rst files each contain a - HowToFit: introduction chapter (detailed step-by-step examples) <https://pyautofit.readthedocs.io/...> line:

• @PyAutoFit/docs/api/model.rst
• @PyAutoFit/docs/api/plot.rst
• @PyAutoFit/docs/api/priors.rst
• @PyAutoFit/docs/api/analysis.rst
• @PyAutoFit/docs/api/database.rst
• @PyAutoFit/docs/api/searches.rst
• @PyAutoFit/docs/api/samples.rst

Rewrite each so the link points to https://github.com/PyAutoLabs/HowToFit (or the matching chapter
folder under notebooks/ where it makes sense — e.g. the priors page can link to chapter 1 if that
covers prior composition; otherwise the repo root).

4. docs/general/workspace.rst — HowToFit section

The "HowToFit" section (lines ~16-24) still describes HowToFit as part of the workspace and links to
the readthedocs tutorials page. Rewrite it as a pointer-style section mirroring the sub-2 phrasing in
autofit_workspace/README.rst: HowToFit now lives in a standalone repo at
https://github.com/PyAutoLabs/HowToFit, clone/browse there for the chapters.

5. docs/features/graphical.rst

Contains two howtofit references (matching autofit_workspace/scripts/features/graphical_models.py that
was updated in sub-2). Rewrite to point at
https://github.com/PyAutoLabs/HowToFit/blob/main/notebooks/chapter_3_graphical_models/.

6. docs/overview/statistical_methods.rst:30

Mirrors autofit_workspace/scripts/overview/overview_3_statistical_methods.py which was updated in
sub-2. Rewrite the URL from
github.com/Jammy2211/autofit_workspace/blob/release/notebooks/howtofit/chapter_graphical_models/tutorial_4_hierachical_models.ipynb
to
github.com/PyAutoLabs/HowToFit/blob/main/notebooks/chapter_3_graphical_models/tutorial_4_hierachical_models.ipynb.

7. docs/cookbooks/multiple_datasets.rst and docs/science_examples/astronomy.rst

Each contains a pyautofit.readthedocs.io/.../howtofit/... URL. Rewrite to the new HowToFit repo
(chapter folder appropriate to the context).

8. README.rst

Three references:

• Top-of-README HowToFit header link (line ~37) → https://github.com/PyAutoLabs/HowToFit
• autofit_workspace GitHub repository ... HowToFit Jupyter notebook lectures sentence (line ~60) →
  drop the /tree/main/notebooks/howtofit sub-link, replace with a separate sentence pointing to the
  standalone HowToFit repo
• The is provided on the HowToFit readthedocs page link (line ~79) → point to the repo README instead

9. paper/paper.md

Three HowToFit references in the published JOSS paper prose. Rewrite URLs and prose to describe
HowToFit as a standalone tutorial repository. Keep the citation language (this is a peer-reviewed
paper — don't rewrite the science, only the URLs and the "part of the workspace" framing).

Out of scope

• Anything under build/lib/howtofit/ — that's generated Sphinx output and will self-heal on next
  docs build.
• Registering the howtofit build target in PyAutoBuild — tracked as a separate follow-up
  (pyautobuild-register) on issue Aggregator With Tag #38.
• Anything in autofit_workspace (done in sub-2) or in the HowToFit repo itself (done in sub-1).

Verification

• grep -rn "howtofit" PyAutoFit --include="*.rst" --include="*.md" --exclude-dir=build should show
  zero matches after the change, aside from the sub-3 commit message itself.
• Sphinx build (cd docs && make html) must succeed without broken-reference warnings for the removed
  howtofit/ toctree entries.

[Jammy2211]

Shipped — 2026-04-22

PR

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

Summary

Deleted the docs/howtofit/ Sphinx chapter tree (4 .rst files), removed the matching toctree entries in docs/index.rst, and rewrote every pyautofit.readthedocs.io/howtofit/... and autofit_workspace/.../howtofit/... URL across 19 files to point at the new standalone PyAutoLabs/HowToFit repository. Net: 19 files changed, +34 / −211 lines. All 1232 unit tests pass; documentation and prose only (no API surface changed).

Session Notes

• docs/index.rst duplicates parts of README.rst (two HowToFit references around lines 25 and 44). Initial survey missed these; caught by the case-sensitive verification grep after first pass.
• docs/features/graphical.rst had two prose-only **HowToFit** references (not URLs). Added explicit hyperlinks to notebooks/chapter_3_graphical_models to match the sub-2 workspace-script treatment and give readers a clickable path.
• paper/paper.md is the published JOSS paper — rewrote URLs and the "included in the workspace" framing only, preserving all scientific prose.
• Outstanding follow-up on umbrella issue Extract howtofit into its own repository autofit_workspace#38: register the howtofit build target in PyAutoBuild so HowToFit notebooks regenerate from scripts automatically.