ready for 0.17.0

docs/_templates/autosummary/enum.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+..  autoclass:: {{ objname }}
+    :show-inheritance:
+
+    {% block attributes %}
+    .. rubric:: Members
+    {% for item in attributes if item[0] is upper %}
+    .. autoattribute:: {{ item }}
+    {%- endfor %}
+
+    {%- for item in attributes if item[0] is not upper %}
+    {%- if loop.first %}
+    .. rubric:: Attributes
+    ..  autosummary::
+        :toctree: .
+    {% endif %}
+        ~{{ name }}.{{ item }}
+    {%- endfor %}
+    {% endblock %}
+
+    {% block methods %}
+    {%- for item in methods if item != "__init__" and item not in inherited_members %}
+    {%- if loop.first %}
+    .. rubric:: Methods
+
+    ..  autosummary::
+        :toctree: .
+    {% endif %}
+        ~{{ name }}.{{ item }}
+    {%- endfor %}
+    {% endblock %}

docs/api/index.md

@@ -14,5 +14,6 @@ scanpy_gpu
 squidpy_gpu
 pertpy_gpu
 decoupler_gpu
+settings
 get
 ```

docs/api/settings.md

@@ -0,0 +1,30 @@
+(settings)=
+
+# Settings
+
+```{eval-rst}
+.. currentmodule:: rapids_singlecell
+```
+
+An object that allows configuring rapids-singlecell.
+
+```{eval-rst}
+.. autosummary::
+   :signatures: none
+   :toctree: generated/
+
+   settings
+   settings.override
+```
+
+Presets allow to set the behavior of many rapids-singlecell functions at once.
+The default follows Scanpy 1; {attr}`~rapids_singlecell.Preset.ScanpyV2Preview` switches to the Scanpy 2 preview defaults:
+
+```{eval-rst}
+.. autosummary::
+   :signatures: none
+   :toctree: generated/
+   :template: enum
+
+   Preset
+```

docs/conf.py

@@ -64,6 +64,7 @@
     "sphinx_copybutton",
     "nbsphinx",
     "scanpydoc",
+    "scverse_misc.sphinx_ext",
     "sphinx.ext.linkcode",
     "sphinx_tabs.tabs",
     "sphinxext.opengraph",
@@ -194,6 +195,10 @@
     ("py:class", "anndata._core.raw.Raw"),
     ("py:class", "scanpy._utils.Empty"),
     ("py:class", "rapids_singlecell._settings.Default"),
+    *[
+        ("py:class", f"rapids_singlecell._settings.{cls}Preset")
+        for cls in ["HVG", "BasicEmbedding", "RankGenesGroups", "Scale", "ScoreGenes"]
+    ],
     ("py:data", "typing.Union"),
     ("py:class", "cuml.linear_model.LogisticRegression"),
     *[

docs/release-notes/0.17.0.md

@@ -1,4 +1,4 @@
-### 0.17.0 {small}`the-future`
+### 0.17.0 {small}`2026-09-09`
 
 ```{rubric} Bug fixes
 ```

docs/usage_principles.md

@@ -13,6 +13,19 @@ import scanpy as sc
 The workflow of *rapids-singlecell* is broadly the same as *scanpy's*.
 For more information, see the tutorials and API documentation.
 
+### Settings
+
+Function defaults follow Scanpy 1. Set {attr}`rsc.settings.preset <rapids_singlecell.settings.preset>` to {attr}`~rapids_singlecell.Preset.ScanpyV2Preview` to opt into the Scanpy 2 preview defaults, either globally or temporarily:
+
+```python
+rsc.settings.preset = "scanpy-v2-preview"
+
+with rsc.settings.override(preset="scanpy-v2-preview"):
+    rsc.pp.pca(adata)  # writes to `adata.obsm["pca"]`
+```
+
+See {ref}`settings` for the full list of presets and what they change.
+
 ### AnnData setup
 
 {class}`~anndata.AnnData` supports GPU-enabled cupy arrays and sparse matrices.

pyproject.toml

@@ -58,6 +58,7 @@ doc = [
     "sphinxext-opengraph",
     "sphinxcontrib.bibtex",
     "scanpydoc[typehints,theme]>=0.9.4",
+    "scverse-misc[sphinx]>=0.1.3",
     "dask",
     "pytest",
 ]

src/rapids_singlecell/_settings.py

@@ -57,39 +57,67 @@ class Preset(enum.StrEnum):
     """Scanpy 1.*’s default settings."""
 
     ScanpyV2Preview = "scanpy-v2-preview"
-    """Scanpy 2.*’s feature default settings. (Preview: subject to change!)"""
+    """Scanpy 2.*’s feature default settings (preview, subject to change!)."""
 
     @property
     def highly_variable_genes(self) -> HVGPreset:
+        """Settings for :func:`~rapids_singlecell.pp.highly_variable_genes`.
+
+        `flavor="seurat", return_df=False` (v1) or `flavor="seurat_v3_paper", return_df=True` (v2).
+        """
         return {
             Preset.ScanpyV1: HVGPreset(flavor="seurat", return_df=False),
             Preset.ScanpyV2Preview: HVGPreset(flavor="seurat_v3_paper", return_df=True),
         }[self]
 
     @property
     def pca(self) -> BasicEmbeddingPreset:
+        """Settings for :func:`~rapids_singlecell.pp.pca`.
+
+        `key_added=None` (v1) or `key_added="pca"` (v2).
+        """
         return self._embedding("pca")
 
     @property
     def umap(self) -> BasicEmbeddingPreset:
+        """Settings for :func:`~rapids_singlecell.tl.umap`.
+
+        `key_added=None` (v1) or `key_added="umap"` (v2).
+        """
         return self._embedding("umap")
 
     @property
     def tsne(self) -> BasicEmbeddingPreset:
+        """Settings for :func:`~rapids_singlecell.tl.tsne`.
+
+        `key_added=None` (v1) or `key_added="tsne"` (v2).
+        """
         return self._embedding("tsne")
 
     @property
     def diffmap(self) -> BasicEmbeddingPreset:
+        """Settings for :func:`~rapids_singlecell.tl.diffmap`.
+
+        `key_added=None` (v1) or `key_added="diffmap"` (v2).
+        """
         return self._embedding("diffmap")
 
     @property
     def draw_graph(self) -> BasicEmbeddingPreset:
+        """Settings for :func:`~rapids_singlecell.tl.draw_graph`.
+
+        `key_added=None` (v1) or `key_added="graph_{layout}"` (v2).
+        """
         return BasicEmbeddingPreset(
             key_added=None if self is Preset.ScanpyV1 else "graph_{layout}"
         )
 
     @property
     def rank_genes_groups(self) -> RankGenesGroupsPreset:
+        """Settings for :func:`~rapids_singlecell.tl.rank_genes_groups`.
+
+        `method="t-test", mean_in_log_space=True` (v1) or `method="wilcoxon", mean_in_log_space=False` (v2).
+        """
         return {
             Preset.ScanpyV1: RankGenesGroupsPreset(
                 method="t-test", mask_var=None, mean_in_log_space=True
@@ -101,10 +129,18 @@ def rank_genes_groups(self) -> RankGenesGroupsPreset:
 
     @property
     def scale(self) -> ScalePreset:
+        """Settings for :func:`~rapids_singlecell.pp.scale`.
+
+        `zero_center=True` (v1) or `zero_center=None` (v2).
+        """
         return ScalePreset(zero_center=True if self is Preset.ScanpyV1 else None)
 
     @property
     def score_genes(self) -> ScoreGenesPreset:
+        """Settings for :func:`~rapids_singlecell.tl.score_genes`.
+
+        `ctrl_as_ref=True` (v1) or `ctrl_as_ref=False` (v2).
+        """
         return ScoreGenesPreset(ctrl_as_ref=self is Preset.ScanpyV1)
 
     def _embedding(self, name: str) -> BasicEmbeddingPreset: