Improve some docs and type hints

docs/conf.py

@@ -258,21 +258,30 @@
 
 # Type aliases
 _TYPE_ALIASES_FULLY_QUALIFIED = {
-    # ------- ._colormodes -------------------------
-    "ridgeplot._color.interpolation.SolidColormode",
+    # ------- ._color.css_colors -------------------
+    "ridgeplot._color.css_colors.CssNamedColor",
+    # ------- ._color.interpolation ----------------
     "ridgeplot._color.interpolation.ColorscaleInterpolants",
+    "ridgeplot._color.interpolation.SolidColormode",
     # ------- ._figure_factory ---------------------
+    "ridgeplot._figure_factory.TraceType",
+    "ridgeplot._figure_factory.TraceTypesArray",
+    "ridgeplot._figure_factory.ShallowTraceTypesArray",
     "ridgeplot._figure_factory.LabelsArray",
     "ridgeplot._figure_factory.ShallowLabelsArray",
     # ------- ._kde --------------------------------
     "ridgeplot._kde.KDEPoints",
     "ridgeplot._kde.KDEBandwidth",
+    "ridgeplot._kde.SampleWeights",
+    "ridgeplot._kde.SampleWeightsArray",
+    "ridgeplot._kde.ShallowSampleWeightsArray",
     # ------- ._missing ----------------------------
     "ridgeplot._missing.MISSING",
     "ridgeplot._missing.MissingType",
     # ------- ._types ------------------------------
     "ridgeplot._types.Color",
     "ridgeplot._types.ColorScale",
+    "ridgeplot._types.NormalisationOption",
     "ridgeplot._types.CollectionL1",
     "ridgeplot._types.CollectionL2",
     "ridgeplot._types.CollectionL3",

docs/reference/changelog.md

@@ -5,7 +5,13 @@ This document outlines the list of changes to ridgeplot between each release. Fo
 Unreleased changes
 ------------------
 
-- ...
+### Documentation
+
+- Small improvements to `ridgeplot()`'s docstring ({gh-pr}`284`)
+
+### Internal
+
+- Small improvements to type hints and annotations ({gh-pr}`284`)
 
 ---
 

src/ridgeplot/_color/interpolation.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal, Protocol
+from typing import TYPE_CHECKING, Literal, Protocol, TypedDict, overload
 
 import plotly.graph_objs as go
 
@@ -63,14 +63,6 @@ def _interpolate_color(colorscale: ColorScale, p: float) -> str:
 # --- Solid color modes
 # ==============================================================
 
-SolidColormode = Literal[
-    "row-index",
-    "trace-index",
-    "trace-index-row-wise",
-    "mean-minmax",
-    "mean-means",
-]
-"""See :paramref:`ridgeplot.ridgeplot.colormode` for more information."""
 
 ColorscaleInterpolants = CollectionL2[float]
 """A :data:`ColorscaleInterpolants` contains the interpolants for a :data:`ColorScale`.
@@ -175,6 +167,15 @@ def _interpolate_mean_means(ctx: InterpolationContext) -> ColorscaleInterpolants
     ]
 
 
+SolidColormode = Literal[
+    "row-index",
+    "trace-index",
+    "trace-index-row-wise",
+    "mean-minmax",
+    "mean-means",
+]
+"""See :paramref:`ridgeplot.ridgeplot.colormode` for more information."""
+
 SOLID_COLORMODE_MAPS: dict[SolidColormode, InterpolationFunc] = {
     "row-index": _interpolate_row_index,
     "trace-index": _interpolate_trace_index,
@@ -202,13 +203,18 @@ def _get_fill_color(p: float) -> str:
     return ((_get_fill_color(p) for p in row) for row in interpolants)
 
 
+class SolidColorsDict(TypedDict):
+    line_color: Color
+    fillcolor: str
+
+
 def _compute_solid_trace_colors(
     colorscale: ColorScale,
     colormode: SolidColormode,
     line_color: Color | Literal["fill-color"],
     opacity: float | None,
     interpolation_ctx: InterpolationContext,
-) -> Generator[Generator[dict[str, Any]]]:
+) -> Generator[Generator[SolidColorsDict]]:
     return (
         (
             dict(
@@ -276,12 +282,17 @@ def _slice_colorscale(
     )
 
 
+class FillgradientColorsDict(TypedDict):
+    line_color: str
+    fillgradient: go.scatter.Fillgradient
+
+
 def _compute_fillgradient_trace_colors(
     colorscale: ColorScale,
     line_color: Color | Literal["fill-color"],
     opacity: float | None,
     interpolation_ctx: InterpolationContext,
-) -> Generator[Generator[dict[str, Any]]]:
+) -> Generator[Generator[FillgradientColorsDict]]:
     solid_line_colors: Generator[Generator[Color]]
     if line_color == "fill-color":
         solid_line_colors = _compute_solid_colors(
@@ -332,13 +343,33 @@ def _compute_fillgradient_trace_colors(
 # ==============================================================
 
 
+@overload
+def compute_trace_colors(
+    colorscale: ColorScale | Collection[Color] | str | None,
+    colormode: Literal["fillgradient"],
+    line_color: Color | Literal["fill-color"],
+    opacity: float | None,
+    interpolation_ctx: InterpolationContext,
+) -> Generator[Generator[FillgradientColorsDict]]: ...
+
+
+@overload
+def compute_trace_colors(
+    colorscale: ColorScale | Collection[Color] | str | None,
+    colormode: SolidColormode,
+    line_color: Color | Literal["fill-color"],
+    opacity: float | None,
+    interpolation_ctx: InterpolationContext,
+) -> Generator[Generator[SolidColorsDict]]: ...
+
+
 def compute_trace_colors(
     colorscale: ColorScale | Collection[Color] | str | None,
     colormode: Literal["fillgradient"] | SolidColormode,
     line_color: Color | Literal["fill-color"],
     opacity: float | None,
     interpolation_ctx: InterpolationContext,
-) -> Generator[Generator[dict[str, Any]]]:
+) -> Generator[Generator[FillgradientColorsDict | SolidColorsDict]]:
     colorscale = validate_and_coerce_colorscale(colorscale)
 
     valid_colormodes = ("fillgradient", *SOLID_COLORMODE_MAPS)

src/ridgeplot/_ridgeplot.py

@@ -111,7 +111,7 @@ def ridgeplot(
 
     Parameters
     ----------
-    samples : Samples or ShallowSamples, optional
+    samples : Samples or ShallowSamples
         If ``samples`` data is specified, Kernel Density Estimation (KDE) will
         be computed. See :paramref:`kernel`, :paramref:`bandwidth`,
         :paramref:`kde_points`, and :paramref:`sample_weights` for more details
@@ -130,7 +130,7 @@ def ridgeplot(
         :paramref:`densities` array with shape :math:`(R, T_r, P_t, 2)`
         (see below for more details).
 
-    densities : Densities or ShallowDensities, optional
+    densities : Densities or ShallowDensities
         If a ``densities`` array is specified, the KDE step will be skipped and
         all associated arguments ignored. Each density array should have shape
         :math:`(R, T_r, P_t, 2)` (4D). Just like the :paramref:`samples`
@@ -182,23 +182,25 @@ def ridgeplot(
         set of samples. Optionally, you can also pass a custom 1D numerical
         array, which will be used for all traces.
 
-    sample_weights : SampleWeightsArray or ShallowSampleWeightsArray or SampleWeights, optional
+    sample_weights : SampleWeightsArray or ShallowSampleWeightsArray or SampleWeights or None
         An (optional) array of KDE weights corresponding to each sample. The
-        weights should be of the same shape as the samples array. If not
+        weights should have the same shape as the samples array. If not
         specified (default), all samples will be weighted equally.
 
-    colorscale : ColorScale or Collection[Color] or str
+    colorscale : ColorScale or Collection[Color] or str or None
         A continuous color scale used to color the different traces in the
         ridgeline plot. It can be represented by a string name (e.g.,
-        ``"viridis"``), a :data:`~ridgeplot._colors.ColorScale` object, or a
-        list of colors (see :data:`~ridgeplot._colors.Color`). If a string name
+        ``"viridis"``), a :data:`~ridgeplot._types.ColorScale` object, or a
+        list of valid :data:`~ridgeplot._colors.Color` objects. If a string name
         is provided, it must be one of the built-in color scales (see
         :func:`~ridgeplot.list_all_colorscale_names()` and
         `Plotly's built-in color-scales`_). If a list of colors is provided, it
         must be a list of valid CSS colors (e.g.,
         ``["rgb(255, 0, 0)", "blue", "hsl(120, 100%, 50%)"]``). The list will
-        ultimately be converted to a :data:`~ridgeplot._colors.ColorScale` object, assuming the
-        colors are evenly spaced.
+        ultimately be converted into a :data:`~ridgeplot._colors.ColorScale`
+        object, assuming the colors provided are evenly spaced. If not specified
+        (default), the color scale will be inferred from current Plotly
+        template.
 
     colormode : "fillgradient" or SolidColormode
         This argument controls the logic used for the coloring of each
@@ -245,26 +247,25 @@ def ridgeplot(
             The default value changed from ``"mean-minmax"`` to
             ``"fillgradient"``.
 
-    opacity : float, optional
+    opacity : float or None
         If None (default), this argument will be ignored and the transparency
-        values of the specifies color-scale will remain untouched. Otherwise,
+        values of the specified color-scale will remain untouched. Otherwise,
         if a float value is passed, it will be used to overwrite the
         opacity/transparency of the color-scale's colors.
 
         .. versionadded:: 0.2.0
             Replaces the deprecated :paramref:`coloralpha` argument.
 
-    labels : LabelsArray or ShallowLabelsArray, optional
-        A list of string labels for each trace. The default value is None,
-        which will result in auto-generated labels of form "Trace n". If,
-        instead, a list of labels is specified, it must be of the same
-        size/length as the number of traces.
+    labels : LabelsArray or ShallowLabelsArray or None
+        A list of string labels for each trace. If not specified (default), the
+        labels will be automatically generated as ``"Trace {n}"``, where ``n``
+        is the trace's index. If instead a list of labels is specified, it
+        should have the same shape as the samples array.
 
-    norm : NormalisationOption, optional
-        The normalisation option to use when normalising the densities. The
-        default is None, which means no normalisation will be applied and the
-        densities will be used as is. The following normalisation options are
-        available:
+    norm : NormalisationOption or None
+        The normalisation option to use when normalising the densities. If not
+        specified (default), no normalisation will be applied and the densities
+        will be used *as is*. The following normalisation options are available:
 
         - ``"probability"`` - normalise the densities by dividing each trace by
           its sum.
@@ -273,7 +274,7 @@ def ridgeplot(
 
         .. versionadded:: 0.2.0
 
-    line_color : Color or "fill-color", optional
+    line_color : Color or "fill-color"
         The color of the traces' lines. Any valid CSS color is allowed
         (default: ``"black"``). If the value is set to "fill-color", the line
         color will be the same as the fill color of the traces (see
@@ -307,7 +308,7 @@ def ridgeplot(
         units of the range between the minimum and maximum x-values from all
         distributions.
 
-    coloralpha : float, optional
+    coloralpha : float
 
         .. deprecated:: 0.2.0
             Use :paramref:`opacity` instead.
@@ -359,6 +360,11 @@ def ridgeplot(
         opacity = coloralpha
 
     if linewidth is not MISSING:
+        if line_width != 1.5:
+            raise ValueError(
+                "You may not specify both the 'linewidth' and 'line_width' arguments! "
+                "HINT: Use the new 'line_width' argument instead of the deprecated 'linewidth'."
+            )
         warnings.warn(
             "The 'linewidth' argument has been deprecated in favor of 'line_width'. "
             "Support for the deprecated argument will be removed in a future version.",

tests/unit/color/test_interpolation.py

@@ -215,7 +215,7 @@ def test_colormode_invalid() -> None:
     ):
         compute_trace_colors(
             colorscale="Viridis",
-            colormode="INVALID",  # type: ignore[arg-type]
+            colormode="INVALID",  # type: ignore[call-overload]
             line_color="black",
             opacity=None,
             interpolation_ctx=InterpolationContext.from_densities([[[(0, 0)]]]),

tests/unit/test_ridgeplot.py

@@ -222,6 +222,14 @@ def test_deprecated_linewidth_is_not_missing() -> None:
         ridgeplot(samples=[[1, 2, 3], [1, 2, 3]], linewidth=0.5)
 
 
+def test_deprecated_linewidth_and_line_width_together_raises() -> None:
+    with pytest.raises(
+        ValueError,
+        match="You may not specify both the 'linewidth' and 'line_width' arguments!",
+    ):
+        ridgeplot(samples=[[1, 2, 3], [1, 2, 3]], linewidth=0.4, line_width=0.6)
+
+
 def test_ridgeplot_colorscale_default_deprecation_warning() -> None:
     with pytest.warns(DeprecationWarning, match="colorscale='default' is deprecated"):
         ridgeplot(samples=[[1, 2, 3], [1, 2, 3]], colorscale="default")