Backport PR #2888 on branch 1.10.x (Updated missing params in docstrings)

docs/release-notes/1.10.2.md

@@ -8,6 +8,7 @@
 ```{rubric} Docs
 ```
 
+* Document several missing parameters in docstring {pr}`2888` {smaller}`S Cheney`
 * Fixed incorrect instructions in "testing" dev docs {pr}`2994` {smaller}`I Virshup`
 * Update marsilea tutorial to use `group_` methods {pr}`3001` {smaller}`I Virshup`
 * Fixed citations {pr}`3032` {smaller}`P Angerer`

scanpy/logging.py

@@ -157,6 +157,11 @@ def print_header(*, file=None):
     """\
     Versions that might influence the numerical results.
     Matplotlib and Seaborn are excluded from this.
+
+    Parameters
+    ----------
+    file
+        Optional path for dependency output.
     """
 
     modules = ["scanpy"] + _DEPENDENCIES_NUMERICS
@@ -171,6 +176,11 @@ def print_versions(*, file: IO[str] | None = None):
     Print versions of imported packages, OS, and jupyter environment.
 
     For more options (including rich output) use `session_info.show` directly.
+
+    Parameters
+    ----------
+    file
+        Optional path for output.
     """
     import session_info
 
@@ -202,6 +212,11 @@ def print_versions(*, file: IO[str] | None = None):
 def print_version_and_date(*, file=None):
     """\
     Useful for starting a notebook so you see when you started working.
+
+    Parameters
+    ----------
+    file
+        Optional path for output.
     """
     from . import __version__
 
@@ -228,7 +243,7 @@ def error(
     Log message with specific level and return current time.
 
     Parameters
-    ==========
+    ----------
     msg
         Message to display.
     time

scanpy/plotting/_docs.py

@@ -43,8 +43,26 @@
     Passed to :meth:`~matplotlib.axes.Axes.quiver`\
 """
 
+doc_cm_palette = """\
+color_map
+    Color map to use for continous variables. Can be a name or a
+    :class:`~matplotlib.colors.Colormap` instance (e.g. `"magma`", `"viridis"`
+    or `mpl.cm.cividis`), see :func:`~matplotlib.pyplot.get_cmap`.
+    If `None`, the value of `mpl.rcParams["image.cmap"]` is used.
+    The default `color_map` can be set using :func:`~scanpy.set_figure_params`.
+palette
+    Colors to use for plotting categorical annotation groups.
+    The palette can be a valid :class:`~matplotlib.colors.ListedColormap` name
+    (`'Set2'`, `'tab20'`, …), a :class:`~cycler.Cycler` object, a dict mapping
+    categories to colors, or a sequence of colors. Colors must be valid to
+    matplotlib. (see :func:`~matplotlib.colors.is_color_like`).
+    If `None`, `mpl.rcParams["axes.prop_cycle"]` is used unless the categorical
+    variable already has colors stored in `adata.uns["{var}_colors"]`.
+    If provided, values of `adata.uns["{var}_colors"]` will be set.\
+"""
+
 # Docs for pl.scatter
-doc_scatter_basic = """\
+doc_scatter_basic = f"""\
 sort_order
     For continuous annotations used as color parameter, plot data points
     with higher values on top of others.
@@ -81,21 +99,7 @@
     Point size. If `None`, is automatically computed as 120000 / n_cells.
     Can be a sequence containing the size for each cell. The order should be
     the same as in adata.obs.
-color_map
-    Color map to use for continous variables. Can be a name or a
-    :class:`~matplotlib.colors.Colormap` instance (e.g. `"magma`", `"viridis"`
-    or `mpl.cm.cividis`), see :func:`~matplotlib.pyplot.get_cmap`.
-    If `None`, the value of `mpl.rcParams["image.cmap"]` is used.
-    The default `color_map` can be set using :func:`~scanpy.set_figure_params`.
-palette
-    Colors to use for plotting categorical annotation groups.
-    The palette can be a valid :class:`~matplotlib.colors.ListedColormap` name
-    (`'Set2'`, `'tab20'`, …), a :class:`~cycler.Cycler` object, a dict mapping
-    categories to colors, or a sequence of colors. Colors must be valid to
-    matplotlib. (see :func:`~matplotlib.colors.is_color_like`).
-    If `None`, `mpl.rcParams["axes.prop_cycle"]` is used unless the categorical
-    variable already has colors stored in `adata.uns["{var}_colors"]`.
-    If provided, values of `adata.uns["{var}_colors"]` will be set.
+{doc_cm_palette}
 na_color
     Color to use for null or masked values. Can be anything matplotlib accepts as a
     color. Used for all points if `color=None`.
@@ -179,13 +183,17 @@
     for instance: the maximum and minimum values (e.g. `vmin=-2, vmax=5`).\
 """
 
-doc_show_save_ax = """\
+doc_show_save = """\
 show
      Show the plot, do not return axis.
 save
     If `True` or a `str`, save the figure.
     A string is appended to the default filename.
-    Infer the filetype if ending on {`'.pdf'`, `'.png'`, `'.svg'`}.
+    Infer the filetype if ending on {`'.pdf'`, `'.png'`, `'.svg'`}.\
+"""
+
+doc_show_save_ax = f"""\
+{doc_show_save}
 ax
     A matplotlib axes object. Only works if plotting a single component.\
 """

scanpy/plotting/_tools/__init__.py

@@ -19,10 +19,12 @@
 from ...get import rank_genes_groups_df
 from .._anndata import ranking
 from .._docs import (
+    doc_cm_palette,
     doc_panels,
     doc_rank_genes_groups_plot_args,
     doc_rank_genes_groups_values_to_plot,
     doc_scatter_embedding,
+    doc_show_save,
     doc_show_save_ax,
     doc_vbound_percentile,
 )
@@ -265,6 +267,7 @@ def dpt_timeseries(
 
 
 @old_positionals("color_map", "palette", "show", "save", "marker")
+@_doc_params(cm_palette=doc_cm_palette, show_save=doc_show_save)
 def dpt_groups_pseudotime(
     adata: AnnData,
     *,
@@ -274,7 +277,18 @@ def dpt_groups_pseudotime(
     save: bool | str | None = None,
     marker: str | Sequence[str] = ".",
 ):
-    """Plot groups and pseudotime."""
+    """\
+    Plot groups and pseudotime.
+
+    Parameters
+    ----------
+    adata
+        Annotated data matrix.
+    {cm_palette}
+    {show_save}
+    marker
+        Marker style. See :mod:`~matplotlib.markers` for details.
+    """
     _, (ax_grp, ax_ord) = plt.subplots(2, 1)
     timeseries_subplot(
         adata.obs["dpt_groups"].cat.codes,

scanpy/preprocessing/_recipes.py

@@ -91,6 +91,17 @@ def recipe_seurat(
 
     Expects non-logarithmized data.
     If using logarithmized data, pass `log=False`.
+
+    Parameters
+    ----------
+    adata
+        Annotated data matrix.
+    log
+        Logarithmize data?
+    plot
+        Show a plot of the gene dispersion vs. mean relation.
+    copy
+        Return a copy if true.
     """
     if copy:
         adata = adata.copy()