docs(plotting): add inline example plots for embedding, scatter, ranking, paga_compare (#1664)

Adds Examples sections with `.. plot::` directives to four public plotting
functions that lacked rendered examples in the API reference:

- sc.pl.embedding: UMAP coloured by cell-type, plus a multi-panel example
- sc.pl.scatter:   obs-vs-obs, gene-vs-gene, and basis-driven panels
- sc.pl.ranking:   top-3 PC loadings, with and without the lowest values
- sc.pl.paga_compare: PAGA graph next to the UMAP embedding

All examples use the bundled sc.datasets.pbmc68k_reduced() so the docs
build stays self-contained and deterministic.

Refs #1664.

Author: Hore01

src/scanpy/plotting/_anndata.py

@@ -157,6 +157,31 @@ def scatter(  # noqa: PLR0913
     -------
     If `show==False` a :class:`~matplotlib.axes.Axes` or a list of it.
 
+    Examples
+    --------
+    Plot two `.obs` annotations against each other and colour by a third.
+
+    .. plot::
+        :context: close-figs
+
+        import scanpy as sc
+        adata = sc.datasets.pbmc68k_reduced()
+        sc.pl.scatter(adata, x="n_counts", y="n_genes", color="bulk_labels")
+
+    Plot expression of two genes against each other.
+
+    .. plot::
+        :context: close-figs
+
+        sc.pl.scatter(adata, x="CD79A", y="CD3D", color="bulk_labels")
+
+    Use a precomputed embedding via the `basis` argument.
+
+    .. plot::
+        :context: close-figs
+
+        sc.pl.scatter(adata, basis="umap", color="bulk_labels")
+
     """
     # color can be a obs column name or a matplotlib color specification (or a collection thereof)
     if color is not None:
@@ -587,6 +612,27 @@ def ranking(  # noqa: PLR0912, PLR0913
     -------
     Returns matplotlib gridspec with access to the axes.
 
+    Examples
+    --------
+    Show the genes with the highest loading on the first three principal components.
+    PCA in :func:`~scanpy.datasets.pbmc68k_reduced` was computed on highly-variable
+    genes only, so we subset to those genes before ranking.
+
+    .. plot::
+        :context: close-figs
+
+        import scanpy as sc
+        adata = sc.datasets.pbmc68k_reduced()
+        adata_hv = adata[:, adata.var["highly_variable"]].copy()
+        sc.pl.ranking(adata_hv, attr="varm", keys="PCs", indices=[0, 1, 2])
+
+    Include the lowest-loading genes alongside the highest.
+
+    .. plot::
+        :context: close-figs
+
+        sc.pl.ranking(adata_hv, attr="varm", keys="PCs", indices=[0, 1, 2], include_lowest=True)
+
     """
     if isinstance(keys, str) and indices is not None:
         scores = getattr(adata, attr)[keys][:, indices]

src/scanpy/plotting/_tools/paga.py

@@ -97,6 +97,18 @@ def paga_compare(  # noqa: PLR0912, PLR0913
     -------
     A list of :class:`~matplotlib.axes.Axes` if `show` is `False`.
 
+    Examples
+    --------
+    Compute a PAGA graph on the bundled PBMC dataset and show it next to the UMAP embedding.
+
+    .. plot::
+        :context: close-figs
+
+        import scanpy as sc
+        adata = sc.datasets.pbmc68k_reduced()
+        sc.tl.paga(adata, groups="bulk_labels")
+        sc.pl.paga_compare(adata, basis="umap")
+
     """
     axs, _, _, _ = _utils.setup_axes(panels=[0, 1], right_margin=right_margin)
     if color is None:

src/scanpy/plotting/_tools/scatterplots.py

@@ -120,6 +120,25 @@ def embedding(  # noqa: PLR0912, PLR0913, PLR0915
     -------
     If `show==False` a :class:`~matplotlib.axes.Axes` or a list of it.
 
+    Examples
+    --------
+    Plot a precomputed UMAP embedding coloured by the `'bulk_labels'` cell-type annotation.
+
+    .. plot::
+        :context: close-figs
+
+        import scanpy as sc
+        adata = sc.datasets.pbmc68k_reduced()
+        sc.pl.embedding(adata, basis="umap", color="bulk_labels")
+
+    Show several panels in a single call by passing a list of keys to `color`,
+    mixing categorical annotations and gene expression.
+
+    .. plot::
+        :context: close-figs
+
+        sc.pl.embedding(adata, basis="umap", color=["bulk_labels", "CD3D", "LYZ"])
+
     """
     #####################
     # Argument handling #