document all intended settings attrs

Author: flying-sheep

docs/extensions/autosummary_skip_deprecated.py

@@ -0,0 +1,32 @@
+"""Extension to skip deprecated methods and properties in autosummary."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Literal
+
+    from sphinx.application import Sphinx
+    from sphinx.ext.autodoc import Options
+
+
+def skip_deprecated(  # noqa: PLR0917
+    app: Sphinx,
+    what: Literal[
+        "module", "class", "exception", "function", "method", "attribute", "property"
+    ],
+    name: str,
+    obj: object,
+    skip: bool,  # noqa: FBT001
+    options: Options | dict[str, object],
+) -> bool | None:
+    """Skip deprecated members."""
+    if hasattr(obj, "__deprecated__"):
+        return True
+    return None
+
+
+def setup(app: Sphinx) -> None:
+    """App setup hook."""
+    app.connect("autodoc-skip-member", skip_deprecated)

docs/release-notes/1.0.0.md

@@ -50,7 +50,7 @@
 - {func}`~scanpy.tl.louvain` provides a better implementation for
   reclustering via `restrict_to` {smaller}`A Wolf`
 - scanpy no longer modifies rcParams upon import, call
-  `settings.set_figure_params` to set the 'scanpy style' {smaller}`A Wolf`
+  :func:`scanpy.set_figure_params` to set the 'scanpy style' {smaller}`A Wolf`
 - default cache directory is `./cache/`, set `settings.cachedir` to change
   this; nested directories in this are avoided {smaller}`A Wolf`
 - show edges in scatter plots based on graph visualization

src/scanpy/__init__.py

@@ -17,7 +17,7 @@
 
 from ._settings import Preset, Verbosity, settings
 
-set_figure_params = settings.set_figure_params
+set_figure_params = settings._set_figure_params
 
 import anndata
 

src/scanpy/_settings.py

@@ -140,8 +140,7 @@ class SettingsMeta(SingletonMeta):
     _logfile: TextIO | None
     _verbosity: Verbosity
     # rest
-    N_PCS: int
-    """Default number of principal components to use."""
+    _n_pcs: int
     _plot_suffix: str
     _file_format_data: AnnDataFileFormat
     _file_format_figs: str
@@ -204,6 +203,16 @@ def verbosity(cls, verbosity: Verbosity | _VerbosityName | int) -> None:
             _type_check(verbosity, "verbosity", (str, int))
         _set_log_level(cls, _VERBOSITY_TO_LOGLEVEL[cls._verbosity.name])
 
+    @property
+    def N_PCS(cls) -> int:
+        """Default number of principal components to use."""
+        return cls._n_pcs
+
+    @N_PCS.setter
+    def N_PCS(cls, n_pcs: int) -> None:
+        _type_check(n_pcs, "n_pcs", int)
+        cls._n_pcs = n_pcs
+
     @property
     def plot_suffix(cls) -> str:
         """Global suffix that is appended to figure filenames."""
@@ -408,6 +417,10 @@ def categories_to_ignore(cls, categories_to_ignore: Iterable[str]) -> None:
     # Functions
     # --------------------------------------------------------------------------------
 
+    @deprecated("Use `scanpy.set_figure_params` instead")
+    def set_figure_params(cls, *args, **kwargs) -> None:
+        cls.set_figure_params(*args, **kwargs)
+
     @old_positionals(
         "scanpy",
         "dpi",
@@ -422,7 +435,7 @@ def categories_to_ignore(cls, categories_to_ignore: Iterable[str]) -> None:
         "transparent",
         "ipython_format",
     )
-    def set_figure_params(  # noqa: PLR0913
+    def _set_figure_params(  # noqa: PLR0913
         cls,
         *,
         scanpy: bool = True,
@@ -532,7 +545,7 @@ def __new__(cls) -> type[Self]:
     _logpath: ClassVar = None
     _verbosity: ClassVar = Verbosity.warning
     # rest
-    N_PCS: ClassVar = 50
+    _n_pcs: ClassVar = 50
     _plot_suffix: ClassVar = ""
     _file_format_data: ClassVar = "h5ad"
     _file_format_figs: ClassVar = "pdf"

src/scanpy/plotting/_rcmod.py

@@ -12,7 +12,7 @@
 def set_rcParams_scanpy(fontsize=14, color_map=None):
     """Set matplotlib.rcParams to Scanpy defaults.
 
-    Call this through `settings.set_figure_params`.
+    Call this through :func:`scanpy.set_figure_params`.
     """
     # figure
     rcParams["figure.figsize"] = (4, 4)