docs(python): improve rendering of API docs type signatures, mark Piv…

…otOps as deprecated, misc tidy-ups (#5388)
pola-rs · Nov 1, 2022 · 9dabbe5 · 9dabbe5
1 parent 7c3fb74
commit 9dabbe5
Show file tree

Hide file tree

Showing 8 changed files with 119 additions and 83 deletions.
diff --git a/py-polars/Makefile b/py-polars/Makefile
@@ -40,6 +40,7 @@ endif
 	$(VENV_ACT_BIN)pip install -U pip
 	$(VENV_ACT_BIN)pip install -r requirements-dev.txt
 	$(VENV_ACT_BIN)pip install -r requirements-lint.txt
+	$(VENV_ACT_BIN)pip install -r docs/requirements-docs.txt
 endif
 
 develop: $(VENV)  ## Build by running `maturin develop`

diff --git a/py-polars/docs/source/conf.py b/py-polars/docs/source/conf.py
@@ -13,6 +13,7 @@
 import datetime
 import inspect
 import os
+import re
 import sys
 import warnings
 
@@ -182,3 +183,28 @@ def linkcode_resolve(domain, info):
     return (
         f"https://github.com/pola-rs/polars/blob/master/py-polars/polars/{fn}{linespec}"
     )
+
+
+def _minify_classpaths(s: str) -> str:
+    # strip private polars classpaths, leaving the classname:
+    # * "pli.Expr" -> "Expr"
+    # * "polars.internals.expr.expr.Expr" -> "Expr"
+    # * "polars.internals.lazyframe.frame.LazyFrame" -> "LazyFrame"
+    return re.sub(
+        pattern=r"~?(pli|polars\.(?:internals|datatypes)[\w.]+?)\.([A-Z][\w.]+)",
+        repl=r"\2",
+        string=s,
+    )
+
+
+def process_signature(app, what, name, obj, opts, sig, ret):
+    return (
+        _minify_classpaths(sig) if sig else sig,
+        _minify_classpaths(ret) if ret else ret,
+    )
+
+
+def setup(app):
+    # TODO: a handful of methods do not seem to trigger the event for
+    #  some reason (possibly @overloads?) - investigate further...
+    app.connect("autodoc-process-signature", process_signature)
diff --git a/py-polars/docs/source/reference/dataframe.rst b/py-polars/docs/source/reference/dataframe.rst
@@ -23,18 +23,6 @@ Attributes
     DataFrame.shape
     DataFrame.width
 
-Conversion
-----------
-.. autosummary::
-   :toctree: api/
-
-    DataFrame.to_arrow
-    DataFrame.to_dict
-    DataFrame.to_dicts
-    DataFrame.to_numpy
-    DataFrame.to_pandas
-    DataFrame.to_struct
-
 Aggregation
 -----------
 .. autosummary::
@@ -50,6 +38,33 @@ Aggregation
     DataFrame.sum
     DataFrame.var
 
+Apply
+-----
+.. autosummary::
+   :toctree: api/
+
+    DataFrame.apply
+
+Computations
+------------
+.. autosummary::
+   :toctree: api/
+
+    DataFrame.fold
+    DataFrame.hash_rows
+
+Conversion
+----------
+.. autosummary::
+   :toctree: api/
+
+    DataFrame.to_arrow
+    DataFrame.to_dict
+    DataFrame.to_dicts
+    DataFrame.to_numpy
+    DataFrame.to_pandas
+    DataFrame.to_struct
+
 Descriptive stats
 -----------------
 .. autosummary::
@@ -64,16 +79,34 @@ Descriptive stats
     DataFrame.n_unique
     DataFrame.null_count
 
-Computations
-------------
+GroupBy
+-------
+This namespace is available after calling :code:`DataFrame.groupby(...)`.
+
+.. currentmodule:: polars.internals.dataframe.groupby
 .. autosummary::
    :toctree: api/
 
-    DataFrame.fold
-    DataFrame.hash_rows
+    GroupBy.agg
+    GroupBy.agg_list
+    GroupBy.apply
+    GroupBy.count
+    GroupBy.first
+    GroupBy.head
+    GroupBy.last
+    GroupBy.max
+    GroupBy.mean
+    GroupBy.median
+    GroupBy.min
+    GroupBy.n_unique
+    GroupBy.pivot
+    GroupBy.quantile
+    GroupBy.sum
+    GroupBy.tail
 
 Manipulation / selection
 ------------------------
+.. currentmodule:: polars
 .. autosummary::
    :toctree: api/
 
@@ -132,55 +165,24 @@ Manipulation / selection
     DataFrame.with_columns
     DataFrame.with_row_count
 
-Apply
------
-.. autosummary::
-   :toctree: api/
-
-    DataFrame.apply
-
-Various
---------
+Miscellaneous
+-------------
 .. autosummary::
    :toctree: api/
 
     DataFrame.frame_equal
     DataFrame.lazy
 
-GroupBy
--------
-This namespace comes available by calling `DataFrame.groupby(..)`.
-
-.. currentmodule:: polars.internals.dataframe.groupby
-
-.. autosummary::
-   :toctree: api/
-
-    GroupBy.agg
-    GroupBy.agg_list
-    GroupBy.apply
-    GroupBy.count
-    GroupBy.first
-    GroupBy.head
-    GroupBy.last
-    GroupBy.max
-    GroupBy.mean
-    GroupBy.median
-    GroupBy.min
-    GroupBy.n_unique
-    GroupBy.pivot
-    GroupBy.quantile
-    GroupBy.sum
-    GroupBy.tail
-
 Pivot
 -----
-This namespace comes available by calling `DataFrame.groupby(..).pivot`
+This namespace is available after calling :code:`DataFrame.groupby(...).pivot`
 
-*Note that this API is deprecated in favor of `DataFrame.pivot`*
+.. deprecated:: 0.13.23
 
-.. currentmodule:: polars.internals.dataframe.pivot
+   Note that this API has been deprecated in favor of :meth:`DataFrame.pivot`
+   and will be removed in a future version.
 
+.. currentmodule:: polars.internals.dataframe.pivot
 .. autosummary::
    :toctree: api/
 

diff --git a/py-polars/docs/source/reference/datatypes.rst b/py-polars/docs/source/reference/datatypes.rst
@@ -1,7 +1,7 @@
 ==========
 Data Types
 ==========
-.. currentmodule:: polars.datatypes
+.. currentmodule:: polars
 
 .. autosummary::
     :toctree: api/

diff --git a/py-polars/docs/source/reference/functions.rst b/py-polars/docs/source/reference/functions.rst
@@ -3,14 +3,6 @@ Functions
 =================
 .. currentmodule:: polars
 
-Config
-~~~~~~
-.. autosummary::
-   :toctree: api/
-
-    toggle_string_cache
-    StringCache
-
 Conversion
 ~~~~~~~~~~
 .. autosummary::
@@ -50,3 +42,11 @@ Parallelization
 
    collect_all
    threadpool_size
+
+StringCache
+~~~~~~~~~~~
+.. autosummary::
+   :toctree: api/
+
+    toggle_string_cache
+    StringCache
diff --git a/py-polars/docs/source/reference/index.rst b/py-polars/docs/source/reference/index.rst
@@ -9,11 +9,11 @@ methods. All classes and functions exposed in ``polars.*`` namespace are public.
    :maxdepth: 2
 
    io
-   functions
    series/index
    dataframe
    lazyframe
    expressions/index
+   functions
    datatypes
    config
    exceptions

diff --git a/py-polars/docs/source/reference/lazyframe.rst b/py-polars/docs/source/reference/lazyframe.rst
@@ -8,6 +8,7 @@ LazyFrame
 
     Representation of a Lazy computation graph/ query.
 
+
 Attributes
 ----------
 
@@ -32,6 +33,22 @@ Aggregation
     LazyFrame.sum
     LazyFrame.var
 
+Apply
+-----
+.. autosummary::
+   :toctree: api/
+
+    LazyFrame.map
+
+Conversion
+----------
+.. autosummary::
+   :toctree: api/
+
+    LazyFrame.from_json
+    LazyFrame.read_json
+    LazyFrame.write_json
+
 Descriptive stats
 -----------------
 .. autosummary::
@@ -82,24 +99,8 @@ Manipulation / selection
     LazyFrame.with_context
     LazyFrame.with_row_count
 
-Conversion
-----------
-.. autosummary::
-   :toctree: api/
-
-    LazyFrame.from_json
-    LazyFrame.read_json
-    LazyFrame.write_json
-
-Apply
------
-.. autosummary::
-   :toctree: api/
-
-    LazyFrame.map
-
-Various
--------
+Miscellaneous
+-------------
 .. autosummary::
    :toctree: api/
 

diff --git a/py-polars/polars/internals/dataframe/pivot.py b/py-polars/polars/internals/dataframe/pivot.py
@@ -14,7 +14,13 @@
 
 
 class PivotOps(Generic[DF]):
-    """Utility class returned in a pivot operation."""
+    """
+    Utility class returned in a pivot operation.
+
+    .. deprecated:: 0.13.23
+          `PivotOps` will be removed in favour of `DataFrame.pivot`.
+
+    """
 
     def __init__(
         self,