docs(api): sync mass.rst with full al.mp namespace + add lmp / lmp_linear sections

[Jammy2211]

Overview

PyAutoLens/docs/api/mass.rst is out of sync with the al.mp.* namespace it documents — multiple exported classes are missing from the autosummary, and the al.lmp.* / al.lmp_linear.* namespaces have no autosummary entries at all. Surfaced as a follow-up while writing the scripts/guides/profiles/mass.py (#178 / #179) and scripts/guides/profiles/light_and_mass_profiles.py (#180 / #181) guides — both guides reference the published API reference URL, so the reference itself should list every class the guides demonstrate.

This is a pure rST docs change. No Python code is modified, no symbols added or removed. The new autosummary entries point at classes that already exist in autogalaxy.profiles.mass.* and autogalaxy.profiles.light_and_mass_profiles and are already re-exported by autolens as al.mp.* / al.lmp.* / al.lmp_linear.*.

Plan

• Add the missing entries to the existing Total, Mass Sheets, Stellar, and Dark sections.
• Add a new Point Mass [ag.mp] section for PointMass, SMBH, SMBHBinary.
• Add a new Stellar Light+Mass [ag.lmp] section listing every class in autogalaxy.profiles.light_and_mass_profiles.
• Add a new Linear Light+Mass [ag.lmp_linear] section listing every class in autogalaxy.profiles.light_linear_and_mass_profiles.
• Keep the existing namespace-label convention (ag.mp, ag.lmp, ag.lmp_linear) used elsewhere in the PyAutoLens docs.
• Keep the existing rST formatting: :toctree: _autosummary, :template: custom-class-template.rst, :recursive: directives per section.
• Optional: run make html in PyAutoLens/docs/ if available to catch any rST errors.

Detailed implementation plan

Affected Repositories

• PyAutoLens (primary) — docs/api/mass.rst edit
• PyAutoGalaxy — read-only reference (no docs/api/mass.rst exists in PyAutoGalaxy; sync is one-way)

Work Classification

Library (docs-only). Ships via /ship_library.

Branch Survey

Repository	Current Branch	Dirty?	Notes
./PyAutoLens	main	clean	free
./PyAutoGalaxy	main	clean	reference only

Suggested branch: feature/docs-mass-rst-sync
Worktree root: ~/Code/PyAutoLabs-wt/docs-mass-rst-sync/
Routing: library-dev → /start_library.

Implementation Steps

1. Edit docs/api/mass.rst to add the missing entries to existing sections and append the new sections. Authoritative class lists derived from the namespace __init__ files:

   • Total [ag.mp] — add: dPIEMass, dPIEMassSph, PIEMass, dPIEPotential, dPIEPotentialSph (these are all defined in autogalaxy/profiles/mass/total/dual_pseudo_isothermal_mass.py and dual_pseudo_isothermal_potential.py).
   • Mass Sheets [ag.mp] — add: ExternalPotential.
   • Stellar [ag.mp] — add: GaussianGradient, SersicCore, SersicCoreSph.
   • Dark [ag.mp] — add: cNFW, cNFWSph, cNFWMCRLudlow, cNFWMCRLudlowSph, cNFWMCRScatterLudlow, cNFWMCRScatterLudlowSph, gNFWVirialMassConcSph, gNFWVirialMassgNFWConcSph, NFWVirialMassConcSph.

2. Append new sections:

   • Point Mass [ag.mp] — list PointMass, SMBH, SMBHBinary. Use :currentmodule: autogalaxy.profiles.mass.
   • Stellar Light+Mass [ag.lmp] — list every class in autogalaxy.profiles.light_and_mass_profiles (Chameleon, ChameleonSph, DevVaucouleurs, DevVaucouleursSph, Exponential, ExponentialSph, ExponentialGradient, ExponentialGradientSph, Gaussian, GaussianGradient, Sersic, SersicSph, SersicCore, SersicCoreSph, SersicGradient, SersicGradientSph). Use :currentmodule: autogalaxy.profiles.light_and_mass_profiles.
   • Linear Light+Mass [ag.lmp_linear] — same class list as ag.lmp (the linear namespace mirrors it class-for-class). Use :currentmodule: autogalaxy.profiles.light_linear_and_mass_profiles.

3. Verify the new file compiles cleanly (if Sphinx is available locally, make html in docs/; otherwise rely on the GitHub Pages build to flag any rST issues).

Key Files

• PyAutoLens/docs/api/mass.rst — add ~80 lines of autosummary entries

Out of scope

• PyAutoLens unit test suite is irrelevant to a docs-only change but /ship_library will still run it as a baseline.
• No corresponding PyAutoGalaxy docs to sync (PyAutoGalaxy has no docs/api/mass.rst).

Constraints / style notes

• Match the existing namespace-label convention ([ag.mp], [ag.lmp], [ag.lmp_linear]) used throughout the PyAutoLens docs even though autolens re-exports them as al.*.
• Match the existing rST directive set (:toctree:, :template:, :recursive:) per section.

Original Prompt

Click to expand starting prompt

Sync PyAutoLens/docs/api/mass.rst to cover every exported al.mp.* class and add documentation sections for al.lmp.* and al.lmp_linear.*. Surfaced as a follow-up while writing the scripts/guides/profiles/{mass.py,light_and_mass_profiles.py} guides (issues #178 / #180) — both guides reference the published API reference URL, so the reference itself should list every class the guides demonstrate.

Gaps to fix in the existing sections:

• Total: add dPIEMass, dPIEMassSph, PIEMass, dPIEPotential, dPIEPotentialSph.
• Mass Sheets: add ExternalPotential (the recently merged line-of-sight potential).
• Stellar: add GaussianGradient, SersicCore, SersicCoreSph.
• Dark: add cNFW, cNFWSph, cNFWMCRLudlow, cNFWMCRLudlowSph, cNFWMCRScatterLudlow, cNFWMCRScatterLudlowSph, gNFWVirialMassConcSph, gNFWVirialMassgNFWConcSph, NFWVirialMassConcSph.

New sections to add:

• Point Mass [ag.mp] — PointMass, SMBH, SMBHBinary.
• Stellar Light+Mass [ag.lmp] — every class in autogalaxy.profiles.light_and_mass_profiles.
• Linear Light+Mass [ag.lmp_linear] — every class in autogalaxy.profiles.light_linear_and_mass_profiles.

Pure rST docs change — no Python code touched. PyAutoGalaxy has no docs/api/mass.rst so the sync is one-way (PyAutoLens only).

[Jammy2211]

Shipped — 2026-05-18 — PR #520 merged. docs/api/mass.rst now covers every al.mp.* class plus new Point Mass, Stellar Light+Mass (al.lmp), and Linear Light+Mass (al.lmp_linear) sections.