docs: update HowToLens references after extraction to standalone repo

[Jammy2211]

Overview

HowToLens has been extracted into its own repository at PyAutoLabs/HowToLens. The bootstrap (sub-task 1) and the autolens_workspace cleanup (sub-task 2, PyAutoLabs/autolens_workspace#80) are both merged — the notebooks under autolens_workspace/notebooks/howtolens/ no longer exist there. The Colab URLs in the PyAutoLens readthedocs chapter pages now point at deleted paths and are 404s. This PR updates all HowToLens references in the PyAutoLens library: migrates URLs to PyAutoLabs/HowToLens (pinned to tag 2026.4.13.6), and reframes prose that described HowToLens as part of the workspace.

Plan

• Migrate ~36 broken Colab URLs across the 5 chapter RST pages to the new repo (PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/..., dropping the old /howtolens/ path prefix).
• Rewrite the HowToLens landing page (docs/howtolens/howtolens.rst) to describe the lecture series as its own repository rather than part of the workspace.
• Update prose in docs/general/workspace.rst, docs/overview/overview_2_new_user_guide.rst, README.rst, and paper/paper.md so HowToLens is presented as a standalone offering.
• Fix the broken file:///Users/Jammy/... link in docs/general/workspace.rst.
• Keep the chapter RST files as readthedocs TOC pages (toctree entries in docs/index.rst remain valid).

Detailed implementation plan

Affected Repositories

• PyAutoLens (primary)

Work Classification

Library

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoLens	main	clean

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

URL migration pattern

• Old: https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/notebooks/howtolens/<chapter>/<tutorial>.ipynb
• New: https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/<chapter>/<tutorial>.ipynb

Note: the path drops /howtolens/ (new repo has chapters directly under notebooks/). HowToLens has been tagged 2026.4.13.6 to match the autolens_workspace version at the time of extraction.

Implementation Steps

1. docs/howtolens/chapter_1_introduction.rst — rewrite 9 Colab URLs.
2. docs/howtolens/chapter_2_lens_modeling.rst — rewrite all Colab URLs.
3. docs/howtolens/chapter_3_search_chaining.rst — rewrite all Colab URLs.
4. docs/howtolens/chapter_4_pixelizations.rst — rewrite all Colab URLs.
5. docs/howtolens/chapter_optional.rst — rewrite 2 Colab URLs.
6. docs/howtolens/howtolens.rst — rewrite intro ("on the autolens workspace" → "in its own repository at PyAutoLabs/HowToLens"); update the Jupyter Notebooks section's reference to scripts folder of the workspace (both notebooks and scripts now ship in the standalone repo).
7. docs/general/workspace.rst:57-65 — rewrite "HowToLens" section as a pointer to PyAutoLabs/HowToLens; replace the broken file:///Users/Jammy/... link with the readthedocs URL https://pyautolens.readthedocs.io/en/latest/howtolens/howtolens.html.
8. docs/overview/overview_2_new_user_guide.rst:81 — replace Jammy2211/autolens_workspace/tree/release/notebooks/howtolens with https://github.com/PyAutoLabs/HowToLens.
9. README.rst:64 — decouple the bundled HowToLens mention; add an explicit PyAutoLabs/HowToLens bullet in the Getting Started list.
10. README.rst:76-84 (HowToLens section) — optionally add a direct repo link alongside the existing readthedocs link.
11. paper/paper.md:88-89 — rewrite "[autolens workspace] ... includes ... the HowToLens lectures" so HowToLens is credited as a separate repo.
12. paper/paper.md:177-185 ("Workspace and HowToLens Tutorials" section) — present the two as separate offerings.

Not Changed

• docs/index.rst toctree — local RST files still exist, toctree stays valid.
• docs/conf.py — no howtolens-specific config.
• Chapter RST file structure — kept as readthedocs TOC pages.
• "HowToLens chapter N" prose references in non-howtolens docs — those chapters still exist in the new repo; no change needed.

Key Files

• docs/howtolens/chapter_1_introduction.rst through chapter_optional.rst — URL migration
• docs/howtolens/howtolens.rst — landing page rewrite
• docs/general/workspace.rst — broken link fix + prose rewrite
• docs/overview/overview_2_new_user_guide.rst — link update
• README.rst, paper/paper.md — prose decoupling

Testing

• Build docs locally (cd docs && make html) and spot-check that chapter pages render and every Colab URL resolves.
• Optionally run the url_check equivalent on the staged changes.

Original Prompt

Click to expand starting prompt

PyAutoLens docs: update after HowToLens extraction

Context

HowToLens has been extracted into its own standalone repository at PyAutoLabs/HowToLens. The bootstrap PR (sub-task 1) and the workspace cleanup (sub-task 2, autolens_workspace PR #80) are both merged. The notebooks that previously lived at autolens_workspace/notebooks/howtolens/ no longer exist there, and the Colab URLs in the PyAutoLens readthedocs that point at them are now 404s. HowToLens has been tagged 2026.4.13.6 to match the autolens_workspace version at the time of extraction.

This is sub-task 3 of the HowToLens extraction project. All changes land in @PyAutoLens (the library repo). No workspace changes.

What to do

URL migration (broken links — must fix)

The 5 chapter RST pages at @PyAutoLens/docs/howtolens/chapter_*.rst are pure RST listings with Colab URLs that need rewriting.

• Old pattern: https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/notebooks/howtolens/<chapter>/<tutorial>.ipynb
• New pattern: https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/<chapter>/<tutorial>.ipynb

Note the path prefix drops /howtolens/ — the new repo has chapters directly under notebooks/.

Files:

• docs/howtolens/chapter_1_introduction.rst — 9 URLs
• docs/howtolens/chapter_2_lens_modeling.rst
• docs/howtolens/chapter_3_search_chaining.rst
• docs/howtolens/chapter_4_pixelizations.rst
• docs/howtolens/chapter_optional.rst — 2 URLs

Prose updates (stale but not broken)

Reframe HowToLens from "shipped inside autolens_workspace" to "its own standalone repository":

• docs/howtolens/howtolens.rst — landing page opens "The best way to learn PyAutoLens is by going through the HowToLens lecture series on the autolens workspace." Rewrite to point at PyAutoLabs/HowToLens. Remove or rewrite the Jupyter Notebooks section's reference to scripts folder of the workspace (HowToLens ships both notebooks and scripts in its own repo now).
• docs/general/workspace.rst:57-65 — "HowToLens" section describes the lectures as part of the workspace. Rewrite as a pointer to the standalone repo. Fix the broken file:///Users/Jammy/.../docs/_build/tutorials/howtolens.html link.
• docs/overview/overview_2_new_user_guide.rst:81 — "checkout the HowToLens package now" link points at Jammy2211/autolens_workspace/tree/release/notebooks/howtolens. Replace with PyAutoLabs/HowToLens.
• README.rst:64 — "The autolens_workspace GitHub repository: example scripts and the HowToLens Jupyter notebook lectures." Decouple — HowToLens is no longer part of the workspace. Add an explicit link to PyAutoLabs/HowToLens in the bulleted list.
• README.rst:76-84 — HowToLens section's readthedocs link is fine. Consider adding a GitHub link to PyAutoLabs/HowToLens as a secondary entry point.
• paper/paper.md:88-89 — "[autolens workspace] ... includes example scripts, lens datasets and the HowToLens lectures in Jupyter notebook format" — decouple the HowToLens mention; keep the workspace mention for the other items.
• paper/paper.md:177-185 ("Workspace and HowToLens Tutorials" section) — reword to present the two as separate offerings; keep the Colab and readthedocs links.

What NOT to change

• docs/index.rst toctree for howtolens — the local .rst files still exist, so the toctree stays valid.
• docs/conf.py — no howtolens-specific config.
• The docs/howtolens/chapter_*.rst files themselves — keep as readthedocs TOC pages; only swap URLs.
• Prose references to "HowToLens chapter N" in non-howtolens docs — those chapters still exist in the new repo and the references remain semantically correct.

Branch / versioning decision

Colab URLs pin to 2026.4.13.6 (HowToLens was tagged to match the workspace version at the time of extraction). Future tags get created by /pre_build once HowToLens is registered in PyAutoBuild (follow-up already tracked in complete.md).

Affected repos

• @PyAutoLens (primary)

Deliverable

One PR on Jammy2211/PyAutoLens titled docs: update HowToLens references after extraction to standalone repo. After merge, all readthedocs HowToLens tutorial links resolve to the new repo, and prose consistently frames HowToLens as a standalone project rather than bundled with the workspace.