docs: render `__Contents__` blocks as Markdown lists

[Jammy2211]

Overview

The __Contents__ block at the top of every workspace tutorial script is meant to act as a per-section index. Today the block is written as a sequence of **Section:** description. lines with no bullet markers, so when PyAutoBuild generates the notebook, GitHub and JupyterLab collapse the entire block into one continuous paragraph in the first markdown cell — exactly the opposite of what the index is for.

The fix is a text-only edit: prefix each entry with - so it renders as a Markdown list. No Python semantics, no notebook execution, no script behaviour change. A worked example already shipped on ic50_workspace (commit 4cde480).

Plan

• Find every .py script in each affected workspace whose module docstring contains a __Contents__ block.
• Rewrite each **Section:** description. entry as - **Section:** description., with continuation lines indented two spaces.
• Spot-check by regenerating one notebook per workspace and visually confirming the contents cell renders as a bullet list.
• Commit per repo (docs: render __Contents__ blocks as Markdown lists); leave notebook regeneration to the next pre_build.
• Open one PR per repo, with autolens_workspace as the lead and siblings cross-referenced.

Detailed implementation plan

Affected Repositories

• autolens_workspace (primary) — 199 files
• autogalaxy_workspace — 101 files
• autofit_workspace — 29 files
• HowToLens — 37 files
• HowToGalaxy — 23 files
• HowToFit — 14 files
• autolens_workspace_test — 1 file
• autogalaxy_workspace_test — 1 file
• autofit_workspace_test — 1 file

Total: ~406 scripts.

Out of scope (no __Contents__ blocks): euclid_strong_lens_modeling_pipeline. Not present locally and skipped: BSc_Galaxies_Project, ic50_workspace.

Work Classification

Workspace.

Branch Survey

Repository	Current Branch	Dirty?
autolens_workspace	main	clean
autogalaxy_workspace	main	clean
autofit_workspace	main	2 unrelated changes (will be stashed)
HowToLens	main	clean
HowToGalaxy	main	clean
HowToFit	main	clean
autolens_workspace_test	main	clean
autogalaxy_workspace_test	main	clean
autofit_workspace_test	main	clean

Suggested branch: feature/contents-block-bullets (uniform across all repos)
Worktree root: ~/Code/PyAutoLabs-wt/contents-block-bullets/ (created later by /start_workspace)

Implementation Steps

1. Create the task worktree and branch feature/contents-block-bullets off origin/main in all 9 repos.
2. For each repo, run a Python helper that, for every *.py under scripts/:
   • Locate the first triple-quoted module docstring.
   • Inside it, find the __Contents__ heading.
   • From the following non-blank line until the next blank line or __Section__ heading, prepend - to lines starting with **, and prepend two spaces to continuation lines that don't start with ** and aren't blank.
   • Skip lines already prefixed with - ** (idempotent).
3. Spot-check by regenerating one notebook per repo (PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py <repo>) and visually confirming the contents cell renders as a bullet list.
4. Commit per repo: docs: render __Contents__ blocks as Markdown lists.
5. Push and open one PR per repo. Mark autolens_workspace as the lead; cross-reference siblings in each PR body.
6. Leave notebook regeneration to the next /pre_build run; do not stage modified .ipynb files in this PR.

Key Files

• scripts/**/*.py in each affected repo — contents-block fix only, inside the top-level module docstring.

Original Prompt

Click to expand starting prompt

Contents block renders as one paragraph in generated notebooks

The problem

Every workspace tutorial script that has a __Contents__ block at the top of
its module docstring uses the same pattern:

__Contents__

**Model:** Compose the lens model fitted to the data.
**Plotters:** Overview of plotting tools used for visualization.
**Dataset Paths:** The `dataset_type` describes the type of data ...
**Grid:** Define the 2d grid of (y,x) coordinates ...

When PyAutoBuild's generate.py converts the script to a notebook, this
block becomes the contents of the first markdown cell. Markdown collapses
consecutive non-blank lines into a single paragraph, so on GitHub
(and in JupyterLab) every contents entry runs together as one continuous
sentence — exactly the opposite of what the index is for.

Confirmed in ic50_workspace's scripts/simulator.py and verified by
inspecting autolens_workspace/notebooks/imaging/simulator.ipynb's top
cell — the same one-big-paragraph rendering appears.

The fix

Convert each **Section:** description. line to a Markdown bullet:

__Contents__

- **Model:** Compose the lens model fitted to the data.
- **Plotters:** Overview of plotting tools used for visualization.
- **Dataset Paths:** The `dataset_type` describes the type of data ...
- **Grid:** Define the 2d grid of (y,x) coordinates ...

Wrapped lines need a 2-space indent so they continue the same list item:

- **Real Data Preview:** Show one example real GDSC2 curve to anchor what
  the simulator is trying to reproduce.

The change is purely Markdown — no Python semantics change, no .py-script
behaviour change, no notebook-execution change. Diff is text-only inside
triple-quoted module docstrings.

A worked example shipped with ic50_workspace (commit
4cde480 on main):
Jammy2211/ic50_workspace@4cde480

Scope

Apply this fix to every script in every workspace that has a
__Contents__ (or equivalent inline index) block in its module docstring.
Confirmed-affected workspaces:

• autolens_workspace
• autogalaxy_workspace
• autofit_workspace
• autolens_workspace_test
• autogalaxy_workspace_test
• autofit_workspace_test
• HowToLens
• HowToGalaxy
• HowToFit
• euclid_strong_lens_modeling_pipeline
• BSc_Galaxies_Project

For each repo:

1. grep -rln "__Contents__" scripts/ to find the affected files.
2. For each file, inside the top-level """...""" module docstring,
   rewrite the __Contents__ block so each **Section:** entry becomes
   a - **Section:** bullet, with continuation lines indented two
   spaces.
3. Spot-check by regenerating the notebook for one or two scripts
   (PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py <project>)
   and visually confirming the cell now renders as a list, not a
   paragraph.
4. Commit per repo with a single tidy commit (e.g.
   docs: render __Contents__ blocks as Markdown lists) and push;
   notebook regeneration is normally handled by the next pre_build
   run, so don't dirty up unrelated notebooks unless the workspace's
   own CI requires it.

Other Markdown paragraph-collapse risks worth a quick scan

Same root cause may bite anywhere a docstring uses adjacent
non-blank lines that the author intended as separate items:

• __Model__ blocks in workspace simulators that list bullet-like items
  with a single leading space ( - foo vs - foo) — these usually do
  render as lists because Markdown allows up to 3 leading spaces, but
  worth eyeballing.
• Any Steps, Notes, Outputs block where each line starts with a
  bold label.

Don't go beyond __Contents__ unless you find an additional concrete
broken example — this prompt's scope is the contents-block fix.

[Jammy2211]

Smoke Test Results — 2026-05-08

All 7 smoke tests passed across autolens_workspace.

Workspace	Passed	Failed	Total
autolens_workspace	7	0	7

[Jammy2211]

Shipped — 2026-05-08

PRs

• docs: render __Contents__ blocks as Markdown lists #139 (lead, 199 scripts)
• docs: render __Contents__ blocks as Markdown lists autogalaxy_workspace#64 (98 scripts)
• docs: render __Contents__ blocks as Markdown lists HowToLens#9 (37 scripts)
• docs: render __Contents__ blocks as Markdown lists HowToGalaxy#6 (21 scripts)
• docs: render __Contents__ blocks as Markdown lists autofit_workspace#54 (1 script)
• docs: render __Contents__ blocks as Markdown lists autolens_workspace_test#83 (1 script)
• docs: render __Contents__ blocks as Markdown lists autogalaxy_workspace_test#36 (1 script)
• docs: render __Contents__ blocks as Markdown lists autofit_workspace_test#25 (1 script)

Summary

Converted __Contents__ blocks across 359 workspace tutorial scripts from plain **Section:** lines into Markdown list bullets. Generated notebooks will now render the contents index as a bulleted list instead of one collapsed paragraph in GitHub/JupyterLab. Notebook regeneration was deliberately deferred — the next /pre_build will pick it up so this PR set stays a clean script-only diff.

Session Notes

• HowToFit had nothing to do — its 14 __Contents__ files were already bulleted (someone fixed them earlier, possibly the same person who shipped the ic50_workspace exemplar). No PR opened against HowToFit.
• Three rewrite-tool bugs were caught during dry-run before any PR was opened, all worth knowing for the next time someone writes a docstring-mass-rewrite tool:
  1. CRLF normalization — Python's read_text() / write_text() silently normalize CRLF→LF. autofit_workspace and HowToFit have many CRLF files, which would have produced 10K-line bogus diffs. Fix: use read_bytes() / write_bytes() and detect/preserve the original line ending byte-for-byte.
  2. Docstring close """ mis-indented — when the contents block ends with the docstring close (no __Section__ heading after the bullets), the "continuation line" heuristic indented """ itself. Fix: terminate the contents-block scan at any line starting with """ or '''.
  3. Prose intro mis-indented — some scripts have an intro sentence between __Contents__ and the first bullet (e.g. "This script is split into the following sections:"). Naively treating it as a continuation line would have indented prose. Fix: skip prose intro until the first ** or - ** line is found, then process from there.
• Visual confirmation: ipynb-py-convert on autolens_workspace/scripts/point_source/simulator.py produced a .ipynb whose first markdown cell has correct - **Section:** bullets — will render as a list on GitHub/JupyterLab.

Out of scope (per the original prompt)

Same paragraph-collapse risk may bite __Model__ blocks, Steps, Notes, Outputs blocks elsewhere. Deliberately not addressed here — the prompt was scoped to __Contents__ and said not to go beyond without a concrete broken example.