Backport PR #3986: docs: deduplicate louvain and leiden parameter docs

Author: LarytheLord

docs/release-notes/3986.doc.md

@@ -0,0 +1 @@
+Clarify and deduplicate shared parameter documentation between {func}`scanpy.tl.leiden` and {func}`scanpy.tl.louvain` {smaller}`Abi`

src/scanpy/tools/_docs.py

@@ -0,0 +1,39 @@
+"""Shared docstrings for tools function parameters."""
+
+from __future__ import annotations
+
+doc_adata = """\
+adata
+    The annotated data matrix.\
+"""
+
+doc_random_state = """\
+random_state
+    Change the initialization of the optimization.\
+"""
+
+doc_restrict_to = """\
+restrict_to
+    Restrict the clustering to the categories within the key for sample
+    annotation, tuple needs to contain `(obs_key, list_of_categories)`.\
+"""
+
+doc_adjacency = """\
+adjacency
+    Sparse adjacency matrix of the graph, defaults to neighbors connectivities.\
+"""
+
+doc_neighbors_key = """\
+neighbors_key
+    Use neighbors connectivities as adjacency.
+    If not specified, {method} looks at .obsp['connectivities'] for connectivities
+    (default storage place for pp.neighbors).
+    If specified, {method} looks at
+    .obsp[.uns[neighbors_key]['connectivities_key']] for connectivities.\
+"""
+
+doc_obsp = """\
+obsp
+    Use .obsp[obsp] as adjacency. You can't specify both
+    `obsp` and `neighbors_key` at the same time.\
+"""

src/scanpy/tools/_leiden.py

@@ -9,7 +9,16 @@
 from .. import _utils
 from .. import logging as logg
 from .._compat import warn
+from .._utils import _doc_params
 from .._utils.random import set_igraph_random_state
+from ._docs import (
+    doc_adata,
+    doc_adjacency,
+    doc_neighbors_key,
+    doc_obsp,
+    doc_random_state,
+    doc_restrict_to,
+)
 from ._utils_clustering import rename_groups, restrict_adjacency
 
 if TYPE_CHECKING:
@@ -29,6 +38,14 @@
             MutableVertexPartition.__module__ = "leidenalg.VertexPartition"
 
 
+@_doc_params(
+    doc_adata=doc_adata,
+    random_state=doc_random_state,
+    restrict_to=doc_restrict_to,
+    adjacency=doc_adjacency,
+    neighbors_key=doc_neighbors_key.format(method="leiden"),
+    obsp=doc_obsp,
+)
 def leiden(  # noqa: PLR0913
     adata: AnnData,
     resolution: float = 1,
@@ -60,22 +77,17 @@ def leiden(  # noqa: PLR0913
 
     Parameters
     ----------
-    adata
-        The annotated data matrix.
+    {doc_adata}
     resolution
         A parameter value controlling the coarseness of the clustering.
         Higher values lead to more clusters.
         Set to `None` if overriding `partition_type`
         to one that doesn’t accept a `resolution_parameter`.
-    random_state
-        Change the initialization of the optimization.
-    restrict_to
-        Restrict the clustering to the categories within the key for sample
-        annotation, tuple needs to contain `(obs_key, list_of_categories)`.
+    {random_state}
+    {restrict_to}
     key_added
         `adata.obs` key under which to add the cluster labels.
-    adjacency
-        Sparse adjacency matrix of the graph, defaults to neighbors connectivities.
+    {adjacency}
     directed
         Whether to treat the graph as directed or undirected.
     use_weights
@@ -91,15 +103,8 @@ def leiden(  # noqa: PLR0913
         Defaults to :class:`~leidenalg.RBConfigurationVertexPartition`.
         For the available options, consult the documentation for
         :func:`~leidenalg.find_partition`.
-    neighbors_key
-        Use neighbors connectivities as adjacency.
-        If not specified, leiden looks at .obsp['connectivities'] for connectivities
-        (default storage place for pp.neighbors).
-        If specified, leiden looks at
-        .obsp[.uns[neighbors_key]['connectivities_key']] for connectivities.
-    obsp
-        Use .obsp[obsp] as adjacency. You can't specify both
-        `obsp` and `neighbors_key` at the same time.
+    {neighbors_key}
+    {obsp}
     copy
         Whether to copy `adata` or modify it inplace.
     flavor

src/scanpy/tools/_louvain.py

@@ -11,7 +11,15 @@
 from .. import _utils
 from .. import logging as logg
 from .._compat import deprecated, old_positionals, pkg_version, warn
-from .._utils import _choose_graph, dematrix
+from .._utils import _choose_graph, _doc_params, dematrix
+from ._docs import (
+    doc_adata,
+    doc_adjacency,
+    doc_neighbors_key,
+    doc_obsp,
+    doc_random_state,
+    doc_restrict_to,
+)
 from ._utils_clustering import rename_groups, restrict_adjacency
 
 if TYPE_CHECKING:
@@ -46,6 +54,14 @@
     "copy",
 )
 @deprecated("Use `scanpy.tl.leiden` instead")
+@_doc_params(
+    doc_adata=doc_adata,
+    random_state=doc_random_state,
+    restrict_to=doc_restrict_to,
+    adjacency=doc_adjacency,
+    neighbors_key=doc_neighbors_key.format(method="louvain"),
+    obsp=doc_obsp,
+)
 def louvain(  # noqa: PLR0912, PLR0913, PLR0915
     adata: AnnData,
     resolution: float | None = None,
@@ -80,22 +96,17 @@ def louvain(  # noqa: PLR0912, PLR0913, PLR0915
 
     Parameters
     ----------
-    adata
-        The annotated data matrix.
+    {doc_adata}
     resolution
         For the default flavor (``'vtraag'``) or for ```RAPIDS```, you can provide a
         resolution (higher resolution means finding more and smaller clusters),
         which defaults to 1.0.
         See “Time as a resolution parameter” in :cite:t:`Lambiotte2014`.
-    random_state
-        Change the initialization of the optimization.
-    restrict_to
-        Restrict the clustering to the categories within the key for sample
-        annotation, tuple needs to contain ``(obs_key, list_of_categories)``.
+    {random_state}
+    {restrict_to}
     key_added
         Key under which to add the cluster labels. (default: ``'louvain'``)
-    adjacency
-        Sparse adjacency matrix of the graph, defaults to neighbors connectivities.
+    {adjacency}
     flavor
         Choose between to packages for computing the clustering.
 
@@ -118,15 +129,8 @@ def louvain(  # noqa: PLR0912, PLR0913, PLR0915
     partition_kwargs
         Key word arguments to pass to partitioning,
         if ``vtraag`` method is being used.
-    neighbors_key
-        Use neighbors connectivities as adjacency.
-        If not specified, louvain looks .obsp['connectivities'] for connectivities
-        (default storage place for pp.neighbors).
-        If specified, louvain looks
-        .obsp[.uns[neighbors_key]['connectivities_key']] for connectivities.
-    obsp
-        Use .obsp[obsp] as adjacency. You can't specify both
-        `obsp` and `neighbors_key` at the same time.
+    {neighbors_key}
+    {obsp}
     copy
         Copy adata or modify it inplace.