docs(python): support tabbed panels in sphinx, add namespace docs (#5540

)

py-polars/docs/requirements-docs.txt

@@ -16,6 +16,7 @@ numpydoc==1.5.0
 pydata-sphinx-theme==0.11.0
 sphinx-autosummary-accessors==2022.4.0
 sphinx-copybutton==0.5.1
+sphinx-design==0.3.0
 sphinx==5.3.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2

py-polars/docs/source/conf.py

@@ -55,6 +55,7 @@
     "numpydoc",
     "sphinx_autosummary_accessors",
     "sphinx_copybutton",
+    "sphinx_design",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

py-polars/docs/source/reference/api.rst

@@ -26,6 +26,99 @@ Available registrations
     register_lazyframe_namespace
     register_series_namespace
 
+
+.. tab-set::
+
+    .. tab-item:: Expr
+
+        .. code-block:: python
+
+            @pl.api.register_expr_namespace("greetings")
+            class Greetings:
+                def __init__(self, expr: pl.Expr):
+                    self._expr = expr
+
+                def hello(self) -> pl.Expr:
+                    return (pl.lit("Hello ") + self._expr).alias("hi there")
+
+                def goodbye(self) -> pl.Expr:
+                    return (pl.lit("Sayōnara ") + self._expr).alias("bye")
+
+
+            pl.DataFrame(data=["world", "world!", "world!!"]).select(
+                [
+                    pl.all().greetings.hello(),
+                    pl.all().greetings.goodbye(),
+                ]
+            )
+
+    .. tab-item:: DataFrame
+
+        .. code-block:: python
+
+            @pl.api.register_dataframe_namespace("split")
+            class SplitFrame:
+                def __init__(self, df: pl.DataFrame):
+                    self._df = df
+
+                def by_alternate_rows(self) -> list[pl.DataFrame]:
+                    df = self._df.with_row_count(name="n")
+                    return [
+                        df.filter((pl.col("n") % 2) == 0).drop("n"),
+                        df.filter((pl.col("n") % 2) != 0).drop("n"),
+                    ]
+
+
+            pl.DataFrame(
+                data=["aaa", "bbb", "ccc", "ddd", "eee", "fff"],
+                columns=[("txt", pl.Utf8)],
+            ).split.by_alternate_rows()
+
+    .. tab-item:: LazyFrame
+
+        .. code-block:: python
+
+            @pl.api.register_lazyframe_namespace("types")
+            class DTypeOperations:
+                def __init__(self, ldf: pl.LazyFrame):
+                    self._ldf = ldf
+
+                def upcast_integer_types(self) -> pl.LazyFrame:
+                    return self._ldf.with_columns(
+                        pl.col(tp).cast(pl.Int64)
+                        for tp in (pl.Int8, pl.Int16, pl.Int32)
+                    )
+
+
+            ldf = pl.DataFrame(
+                data={"a": [1, 2], "b": [3, 4], "c": [5.6, 6.7]},
+                columns=[("a", pl.Int16), ("b", pl.Int32), ("c", pl.Float32)],
+            ).lazy()
+
+            ldf.types.upcast_integer_types()
+
+    .. tab-item:: Series
+
+        .. code-block:: python
+
+            @pl.api.register_series_namespace("math")
+            class MathShortcuts:
+                def __init__(self, s: pl.Series):
+                    self._s = s
+
+                def square(self) -> pl.Series:
+                    return self._s * self._s
+
+                def cube(self) -> pl.Series:
+                    return self._s * self._s * self._s
+
+
+            s = pl.Series("n", [1, 2, 3, 4, 5])
+
+            s2 = s.math.square().rename("n2", in_place=True)
+            s3 = s.math.cube().rename("n3", in_place=True)
+
+
 .. note::
 
    You cannot override existing polars namespaces (such as ``.str`` or ``.dt``), and attempting to do so

py-polars/polars/api.py

@@ -113,6 +113,12 @@ def register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     │ 64.001 ┆ 128       ┆ 64        ┆ 64           │
     └────────┴───────────┴───────────┴──────────────┘
 
+    See Also
+    --------
+    register_dataframe_namespace: Register functionality on a DataFrame.
+    register_lazyframe_namespace: Register functionality on a LazyFrame.
+    register_series_namespace: Register functionality on a Series.
+
     """
     return _create_namespace(name, Expr)
 
@@ -217,6 +223,12 @@ def register_dataframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     │ yz  ┆ 6   ┆ 7   ┆ 8   │
     └─────┴─────┴─────┴─────┘]
 
+    See Also
+    --------
+    register_expr_namespace: Register functionality on an Expr.
+    register_lazyframe_namespace: Register functionality on a LazyFrame.
+    register_series_namespace: Register functionality on a Series.
+
     """
     return _create_namespace(name, DataFrame)
 
@@ -293,6 +305,12 @@ def register_lazyframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     │ 6   ┆ 7   ┆ 8   │
     └─────┴─────┴─────┘]
 
+    See Also
+    --------
+    register_expr_namespace: Register functionality on an Expr.
+    register_dataframe_namespace: Register functionality on a DataFrame.
+    register_series_namespace: Register functionality on a Series.
+
     """
     return _create_namespace(name, LazyFrame)
 
@@ -309,12 +327,15 @@ def register_series_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
     Examples
     --------
     >>> @pl.api.register_series_namespace("math")
-    ... class CustomMath:
+    ... class MathShortcuts:
     ...     def __init__(self, s: pl.Series):
     ...         self._s = s
     ...
     ...     def square(self) -> pl.Series:
     ...         return self._s * self._s
+    ...
+    ...     def cube(self) -> pl.Series:
+    ...         return self._s * self._s * self._s
     >>>
     >>> s = pl.Series("n", [1.5, 31.0, 42.0, 64.5])
     >>> s.math.square().alias("s^2")
@@ -326,6 +347,23 @@ def register_series_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
         1764.0
         4160.25
     ]
+    >>> s = pl.Series("n", [1, 2, 3, 4, 5])
+    >>> s.math.cube().alias("s^3")
+    shape: (5,)
+    Series: 's^3' [i64]
+    [
+        1
+        8
+        27
+        64
+        125
+    ]
+
+    See Also
+    --------
+    register_expr_namespace: Register functionality on an Expr.
+    register_dataframe_namespace: Register functionality on a DataFrame.
+    register_lazyframe_namespace: Register functionality on a LazyFrame.
 
     """
     return _create_namespace(name, Series)