Fix docs for new plotting classes (scverse#1309)

Co-authored-by: Philipp A <[email protected]>

docs/conf.py

@@ -137,6 +137,9 @@ def setup(app):
     "sklearn.neighbors.dist_metrics.DistanceMetric": "sklearn.neighbors.DistanceMetric",
     # If the docs are built with an old version of numpy, this will make it work:
     "numpy.random.RandomState": "numpy.random.mtrand.RandomState",
+    "scanpy.plotting._matrixplot.MatrixPlot": "scanpy.pl.MatrixPlot",
+    "scanpy.plotting._dotplot.DotPlot": "scanpy.pl.DotPlot",
+    "scanpy.plotting._stacked_violin.StackedViolin": "scanpy.pl.StackedViolin",
 }
 
 nitpick_ignore = [

scanpy/plotting/__init__.py

@@ -1,7 +1,7 @@
 from ._anndata import scatter, violin, ranking, clustermap, tracksplot, dendrogram, correlation_matrix, heatmap
-from ._dotplot import dotplot
-from ._matrixplot import matrixplot
-from ._stacked_violin import stacked_violin
+from ._dotplot import DotPlot, dotplot
+from ._matrixplot import MatrixPlot, matrixplot
+from ._stacked_violin import StackedViolin, stacked_violin
 from ._preprocessing import filter_genes_dispersion, highly_variable_genes
 
 from ._tools.scatterplots import embedding, pca, diffmap, draw_graph, tsne, umap, spatial
@@ -51,6 +51,19 @@
    pl.dendrogram
 
 
+Classes
+-------
+
+These classes allow fine tuning of visual parameters. 
+
+.. autosummary::
+   :toctree: .
+
+    pl.DotPlot
+    pl.MatrixPlot
+    pl.StackedViolin
+
+
 Preprocessing
 -------------
 

scanpy/plotting/_baseplot_class.py

@@ -38,7 +38,6 @@
 return_fig
     Returns :class:`DotPlot` object. Useful for fine-tuning
     the plot. Takes precedence over `show=False`.
-
 """
 
 
@@ -165,7 +164,9 @@ def swap_axes(self, swap_axes: Optional[bool] = True):
 
         Parameters
         ----------
-        swap_axes : bool, default: True
+        swap_axes
+            Boolean to turn on (True) or off (False) 'add_dendrogram'. Default True
+
 
         Returns
         -------
@@ -186,7 +187,7 @@ def add_dendrogram(
         dendrogram_key: Optional[str] = None,
         size: Optional[float] = 0.8,
     ):
-        """
+        """\
         Show dendrogram based on the hierarchical clustering between the `groupby`
         categories. Categories are reordered to match the dendrogram order.
 
@@ -200,23 +201,29 @@ def add_dendrogram(
         `var_names` are reordered to produce a more pleasing output if:
             * The data contains `var_groups`
             * the `var_groups` match the categories.
+
         The previous conditions happen by default when using Plot
-        to show the results from `sc.tl.rank_genes_groups` (aka gene markers), by
-        calling `sc.tl.rank_genes_groups_(plot_name)`.
+        to show the results from :func:`~scanpy.tl.rank_genes_groups` (aka gene markers), by
+        calling `scanpy.tl.rank_genes_groups_(plot_name)`.
+
 
         Parameters
         ----------
-        show : bool, default True
-        dendrogram_key : str, default None
+        show
+            Boolean to turn on (True) or off (False) 'add_dendrogram'
+        dendrogram_key
             Needed if `sc.tl.dendrogram` saved the dendrogram using a key different
             than the default name.
-        size : size of the dendrogram. Corresponds to width when dendrogram shown on
+        size
+            size of the dendrogram. Corresponds to width when dendrogram shown on
             the right of the plot, or height when shown on top.
 
+
         Returns
         -------
         BasePlot
 
+
         Examples
         --------
         >>> adata = sc.datasets.pbmc68k_reduced()
@@ -261,25 +268,34 @@ def add_totals(
         size: Optional[float] = 0.8,
         color: Optional[Union[ColorLike, Sequence[ColorLike]]] = None,
     ):
-        """
+        """\
         Show barplot for the number of cells in in `groupby` category.
 
         The barplot is by default shown on the right side of the plot or on top
         if the axes are swapped.
 
+
         Parameters
         ----------
-        show : bool, default True
-        sort : Set to either 'ascending' or 'descending' to reorder the categories
+        show
+            Boolean to turn on (True) or off (False) 'add_dendrogram'
+        sort
+            Set to either 'ascending' or 'descending' to reorder the categories
             by cell number
-        size : size of the barplot. Corresponds to width when shown on
+        size
+            size of the barplot. Corresponds to width when shown on
             the right of the plot, or height when shown on top.
-        color: Color for the bar plots or list of colors for each of the bar plots.
-            By default, each bar plot uses the colors assigned in `adata.uns[{groupby}_colors.
+        color
+            Color for the bar plots or list of colors for each of the bar plots.
+            By default, each bar plot uses the colors assigned in
+            `adata.uns[{groupby}_colors]`.
+
+
         Returns
         -------
         BasePlot
 
+
         Examples
         --------
         >>> adata = sc.datasets.pbmc68k_reduced()
@@ -311,6 +327,19 @@ def add_totals(
         return self
 
     def style(self, cmap: Optional[str] = DEFAULT_COLORMAP):
+        """\
+        Set visual style parameters
+
+        Parameters
+        ----------
+        cmap
+            colormap
+
+        Returns
+        -------
+        BasePlot
+        """
+
         self.cmap = cmap
 
     def legend(
@@ -319,24 +348,31 @@ def legend(
         title: Optional[str] = DEFAULT_COLOR_LEGEND_TITLE,
         width: Optional[float] = DEFAULT_LEGENDS_WIDTH,
     ):
-        """
-        Configure legend parameters.
+        """\
+        Configure legend parameters
 
         Parameters
         ----------
         show
-            Set to `False` to hide the default plot of the legend.
+            Set to 'False' to hide the default plot of the legend. This sets the
+            legend width to zero which will result in a wider main plot.
         title
-            Title for the dot size legend. Use "\n" to add line breaks.
+            Legend title. Appears on top of the color bar. Use '\\n' to add line breaks.
         width
-            Width of the legend.
+            Width of the legend. The value is a proportion with respect
+            to the figure width. E.g. 0.5 means the legend width is 50% of the figure
+            width.
 
         Returns
         -------
         BasePlot
 
+
         Examples
         --------
+
+        Set legend title:
+
         >>> adata = sc.datasets.pbmc68k_reduced()
         >>> markers = {{'T-cell': 'CD3D', 'B-cell': 'CD79A', 'myeloid': 'CST3'}}
         >>> dp = sc.pl.BasePlot(adata, markers, groupby='bulk_labels')