Merge pull request #43 from pydiverse/api-doku

API documentation
pydiverse · Dec 18, 2024 · 62965ba · 62965ba
2 parents 58eb515 + 366aa9a
commit 62965ba
Show file tree

Hide file tree

Showing 38 changed files with 11,165 additions and 14,581 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,7 @@
+# documentation files that are generated on build
+
+docs/**/pydiverse.transform.*.rst
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -59,6 +59,7 @@ repos:
         entry: pixi run check-merge-conflict --assume-in-merge
         language: system
         types: [text]
+        exclude: ".rst$"
       # typos
       - id: typos
         name: typos

diff --git a/docs/source/_templates/autosummary/accessor_method.rst b/docs/source/_templates/autosummary/accessor_method.rst
@@ -0,0 +1,6 @@
+{{ '.'.join(objname.split('.')[-2:]) }}
+{{ underline }}
+
+.. currentmodule:: {{ '.'.join(module.split('.')[:2]) }}
+
+.. autoaccessormethod:: {{ (module.split('.')[2:] + [objname]) | join('.') }}
diff --git a/docs/source/_templates/autosummary/short_title.rst b/docs/source/_templates/autosummary/short_title.rst
@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -10,6 +10,7 @@
 
 import sphinx.util
 from sphinx.ext.napoleon import GoogleDocstring
+import sphinx_autosummary_accessors
 
 
 sys.path.insert(0, os.path.abspath("../../src"))
@@ -38,8 +39,11 @@
     "sphinx.ext.intersphinx",
     # "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx_autosummary_accessors"
 ]
 
+maximum_signature_line_length = 100
+
 myst_enable_extensions = [
     "fieldlist",
     "deflist",
@@ -53,6 +57,8 @@
 
 autosectionlabel_prefix_document = True
 
+toc_object_entries_show_parents = "all"
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "sa": ("https://docs.sqlalchemy.org/en/stable", None),
@@ -64,7 +70,7 @@
     "Config File",
 ]
 
-templates_path = ["_templates"]
+templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
 exclude_patterns = []
 
 

diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst
@@ -1,49 +1,17 @@
+===
 API
 ===
 
-Core
-----
-
-.. automodule:: pydiverse.transform
-    :members:
-    :undoc-members:
-
-    .. autodata:: pydiverse.transform.λ
-
-
-Builtin Verbs
--------------
-
-.. automodule:: pydiverse.transform.core.verbs
-    :members:
-    :undoc-members:
-
-
-Operators
----------
-
-.. automodule:: pydiverse.transform.core.ops.aggregate
-    :members:
-.. automodule:: pydiverse.transform.core.ops.logical
-    :members:
-.. automodule:: pydiverse.transform.core.ops.numeric
-    :members:
-.. automodule:: pydiverse.transform.core.ops.string
-    :members:
-.. automodule:: pydiverse.transform.core.ops.window
-    :members:
-
-
-Functions
----------
-
-.. automodule:: pydiverse.transform.core.functions
-    :members:
-    :undoc-members:
+.. toctree::
+    :maxdepth: 1
 
+    verbs
+    operators/index
+    targets
 
-Table Implementations
----------------------
+Table
+-----
 
-.. autoclass:: pydiverse.transform.eager.PandasTableImpl
-.. autoclass:: pydiverse.transform.lazy.SQLTableImpl
+.. currentmodule:: pydiverse.transform
+.. autoclass:: Table
+    :noindex:
diff --git a/docs/source/reference/operators/aggregation.rst b/docs/source/reference/operators/aggregation.rst
@@ -0,0 +1,17 @@
+===========
+Aggregation
+===========
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    count
+    all
+    any
+    max
+    mean
+    min
+    sum
diff --git a/docs/source/reference/operators/arithmetic.rst b/docs/source/reference/operators/arithmetic.rst
@@ -0,0 +1,17 @@
+==========
+Arithmetic
+==========
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    __add__
+    __floordiv__
+    __mul__
+    __neg__
+    __pos__
+    __sub__
+    __truediv__
diff --git a/docs/source/reference/operators/comparison.rst b/docs/source/reference/operators/comparison.rst
@@ -0,0 +1,22 @@
+==========
+Comparison
+==========
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    __eq__
+    __ge__
+    __gt__
+    __le__
+    __lt__
+    __ne__
+    is_inf
+    is_nan
+    is_not_inf
+    is_not_nan
+    is_not_null
+    is_null
diff --git a/docs/source/reference/operators/datetime.rst b/docs/source/reference/operators/datetime.rst
@@ -0,0 +1,26 @@
+===================
+Datetime / Duration
+===================
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/accessor_method.rst
+
+    dt.day
+    dt.day_of_week
+    dt.day_of_year
+    dt.hour
+    dt.microsecond
+    dt.millisecond
+    dt.minute
+    dt.month
+    dt.second
+    dt.year
+    dur.days
+    dur.hours
+    dur.microseconds
+    dur.milliseconds
+    dur.minutes
+    dur.seconds
diff --git a/docs/source/reference/operators/horizontal_aggregation.rst b/docs/source/reference/operators/horizontal_aggregation.rst
@@ -0,0 +1,17 @@
+======================
+Horizontal Aggregation
+======================
+
+.. currentmodule:: pydiverse.transform
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    coalesce
+    count
+    all
+    any
+    max
+    min
+    sum
diff --git a/docs/source/reference/operators/index.rst b/docs/source/reference/operators/index.rst
@@ -0,0 +1,41 @@
+=================
+Column Operations
+=================
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   arithmetic
+   logical
+   comparison
+   numerical
+   string
+   datetime
+   aggregation
+   window
+   sorting_markers
+   horizontal_aggregation
+
+
+.. currentmodule:: pydiverse.transform
+
+.. autoclass:: ColExpr
+   :no-index:
+   :members: dtype
+
+.. autosummary::
+    :toctree: _generated/
+    :template: autosummary/short_title.rst
+    :nosignatures:
+
+    lit
+    when
+
+.. autosummary::
+    :toctree: _generated/
+    :template: autosummary/short_title.rst
+    :nosignatures:
+
+    ColExpr.cast
+    ColExpr.map
diff --git a/docs/source/reference/operators/logical.rst b/docs/source/reference/operators/logical.rst
@@ -0,0 +1,21 @@
+=======
+Logical
+=======
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    __and__
+    __invert__
+    __or__
+    __xor__
+    any
+    all
+    is_in
+    is_not_null
+    is_null
+    fill_null
+    map
diff --git a/docs/source/reference/operators/numerical.rst b/docs/source/reference/operators/numerical.rst
@@ -0,0 +1,21 @@
+=========
+Numerical
+=========
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    __pow__
+    abs
+    ceil
+    exp
+    floor
+    is_inf
+    is_nan
+    is_not_inf
+    is_not_nan
+    log
+    round
diff --git a/docs/source/reference/operators/sorting_markers.rst b/docs/source/reference/operators/sorting_markers.rst
@@ -0,0 +1,14 @@
+===============
+Sorting Markers
+===============
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    ascending
+    descending
+    nulls_first
+    nulls_last
diff --git a/docs/source/reference/operators/string.rst b/docs/source/reference/operators/string.rst
@@ -0,0 +1,21 @@
+======
+String
+======
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/accessor_method.rst
+
+    str.contains
+    str.ends_with
+    str.len
+    str.lower
+    str.replace_all
+    str.slice
+    str.starts_with
+    str.strip
+    str.to_date
+    str.to_datetime
+    str.upper
diff --git a/docs/source/reference/operators/window.rst b/docs/source/reference/operators/window.rst
@@ -0,0 +1,21 @@
+======
+Window
+======
+
+.. currentmodule:: pydiverse.transform.ColExpr
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    shift
+
+.. currentmodule:: pydiverse.transform
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    dense_rank
+    rank
+    row_number
diff --git a/docs/source/reference/targets.rst b/docs/source/reference/targets.rst
@@ -0,0 +1,14 @@
+=========================
+Backends / Export Targets
+=========================
+
+.. currentmodule:: pydiverse.transform
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+    :template: autosummary/short_title.rst
+
+    DuckDb
+    Pandas
+    Polars
+    SqlAlchemy