From 66c3a69c2dc0380a7c05796f130be1405ef8b430 Mon Sep 17 00:00:00 2001
From: Jammy2211 <JNightingale2211@gmail.com>
Date: Thu, 9 Jul 2026 17:01:36 +0100
Subject: [PATCH] docs: document the functional plot API in plot.rst

Follow-up to the #592 prune of the removed OO plotting subsystem. Adds a
'Plot Customization' section documenting the functional interface (title/
colormap/use_log10/output_path/output_filename/output_format kwargs on any
aplt.* call; config/visualize YAML for defaults) and a 'Figure Output'
section for the surviving autoarray.plot.Output object. Re-audit clean.

Issue PyAutoLabs/PyAutoLens#595.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/api/plot.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/docs/api/plot.rst b/docs/api/plot.rst
index 8f86633df..8edfe538c 100644
--- a/docs/api/plot.rst
+++ b/docs/api/plot.rst
@@ -97,3 +97,52 @@ Module-level functions for visualizing non-linear search results.
    corner_anesthetic
    subplot_parameters
    log_likelihood_vs_iteration
+
+Plot Customization [aplt]
+-------------------------
+
+The plotting API is **functional**: customization is done by passing keyword
+arguments directly to any ``aplt`` plotting function. There is no ``MatPlot2D``
+object anymore (nor the old ``Cmap`` / ``Visuals`` / ``Units`` / matplotlib-wrapper
+classes) — these were removed in favour of the keyword-argument interface below.
+
+Every figure and subplot function accepts:
+
+- ``title`` — the figure title.
+- ``colormap`` — the matplotlib colormap name (e.g. ``"jet"``, ``"hot"``, ``"gray"``).
+- ``use_log10`` — if ``True``, plot the colormap on a ``log10`` scale.
+- ``output_path`` — directory to save the figure to (omit to display it interactively).
+- ``output_filename`` — the saved file's name.
+- ``output_format`` — the saved file's format, e.g. ``"png"`` or ``"pdf"``.
+
+For example:
+
+.. code-block:: python
+
+    import autolens.plot as aplt
+
+    # Customize the appearance:
+    aplt.plot_array(array=image, title="Image", colormap="jet", use_log10=True)
+
+    # Save to disk instead of displaying:
+    aplt.plot_array(
+        array=image, output_path="output", output_filename="image", output_format="png"
+    )
+
+Default plotting values (figure size, fonts, colormaps, ticks, labels, ...) are set
+via the workspace ``config/visualize`` YAML files rather than in code, so most figures
+need no customization at all.
+
+Figure Output [aplt]
+--------------------
+
+The ``Output`` object gives lower-level control of how and where figures are written
+to disk, and is accepted by the plotting functions in place of the individual
+``output_*`` keyword arguments.
+
+.. currentmodule:: autoarray.plot
+
+.. autosummary::
+   :toctree: _autosummary
+
+   Output