docs: document the functional plot API in plot.rst

docs/api/plot.rst

@@ -78,3 +78,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 autogalaxy.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