docs: Change to Google Doc Style (#712)

This produces better rendering in the eventual docs, including using the
type hints to determine the parameter and return types.

.github/workflows/ci_python.yml

@@ -68,9 +68,6 @@ jobs:
       - name: isort
         run: |
           poetry run isort --filter-files --diff pysrc pytests docs/source
-      - name: darglint
-        run: |
-          poetry run darglint pysrc
       - name: pydocstyle
         run: |
           poetry run pydocstyle pysrc

python/Cargo.toml

@@ -3,7 +3,7 @@ name = "kaskada"
 authors = ["Kaskada Developers"]
 edition = "2021"
 license = "Apache-2.0"
-version = "0.6.0-a.1"
+version = "0.6.0-a.2"
 description = """
 Python library for building and executing temporal queries.
 """

python/docs/source/conf.py

@@ -20,6 +20,7 @@
     # "myst_parser",
     "myst_nb",
     "sphinx_copybutton",
+    "sphinx_autodoc_typehints",  # must be after napoleon
     "_extensions.gallery_directive",
 ]
 autodoc_typehints = "description"
@@ -110,12 +111,18 @@
 # Automatically extract typehints when specified and place them in
 # descriptions of the relevant function/method.
 autodoc_typehints = "description"
+autodoc_type_aliases = {"kaskada.Arg": "kaskada.Arg"}
 
 # Don't show class signature with the class' name.
 autodoc_class_signature = "separated"
 
 autosummary_generate = True
 
 napoleon_preprocess_types = True
+napoleon_attr_annotations = True
+napoleon_use_rtype = False
+typehints_use_rtype = False
+typehints_document_rtype = False
+typehints_defaults = "comma"
 
 suppress_warnings = ["mystnb.unknown_mime_type"]

python/docs/source/examples/time_centric.ipynb

@@ -81,7 +81,7 @@
     "## Kaskada Client Setup\n",
     "\n",
     "```\n",
-    "%pip install kaskada>=0.6.0-a.1\n",
+    "%pip install kaskada>=0.6.0-a.0\n",
     "```"
    ]
   },
@@ -339,4 +339,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

python/docs/source/index.md

@@ -1,7 +1,11 @@
 ---
 hide-toc: true
 html_theme.sidebar_secondary.remove: true
+sd_hide_title: true
 ---
+
+# Real-Time AI without the fuss.
+
 <div class="px-4 py-5 my-5 text-center">
     <img class="d-block mx-auto mb-4 only-light" src="_static/kaskada-positive.svg" alt="" width="50%">
     <img class="d-block mx-auto mb-4 only-dark" src="_static/kaskada-negative.svg" alt="" width="50%">
@@ -12,7 +16,7 @@ html_theme.sidebar_secondary.remove: true
     </div>
 </div>
 
-# Kaskada completes the Real-Time AI stack, providing...
+## Kaskada completes the Real-Time AI stack, providing...
 
 ```{gallery-grid}
 :grid-columns: 1 2 2 3

python/docs/source/reference/timestream/aggregation.md

@@ -2,12 +2,16 @@
 
 Timestream aggregations are:
 
-Cumulative:
-    They reflect all values up to and including the current time.
-Grouped:
-    They reflect the values for each entity separately.
-Windowed:
-    They reflect the values within a specific [window](../windows.md).
+Cumulative
+: They reflect all values up to and including the current time.
+
+Grouped
+: They reflect the values for each entity separately.
+
+Windowed
+: They reflect the values within a specific [window](../windows.md).
+
+## Aggregation Methods
 
 ```{eval-rst}
 .. currentmodule:: kaskada

python/docs/source/reference/timestream/arithmetic.md

@@ -8,6 +8,8 @@ For instance, `a.add(b)` may be written as `a + b`.
 See the notes on the specific functions for more information.
 ```
 
+## Arithmetic Methods
+
 ```{eval-rst}
 .. currentmodule:: kaskada
 

python/docs/source/reference/timestream/collection.md

@@ -1,7 +1,9 @@
-# Arithmetic
+# Collection
 
 Timestreams allow each point to contain a collection -- a `list` or `map` -- of elements.
 
+## Collection Methods
+
 ```{eval-rst}
 .. currentmodule:: kaskada
 

python/docs/source/reference/timestream/comparison.md

@@ -10,6 +10,8 @@ See the notes on the specific functions for more information.
 To respect the semantics of `__eq__` and `__ne__`, `a == b` and `a != b` are *not* overloaded.
 ```
 
+## Comparison Methods
+
 ```{eval-rst}
 .. currentmodule:: kaskada
 

python/docs/source/reference/timestream/index.md

@@ -12,6 +12,7 @@ html_theme.sidebar_secondary.remove:
     :exclude-members: __init__
 
     .. autoproperty:: data_type
+.. autoclass:: kaskada.Arg
 ```
 
 ```{toctree}

python/docs/source/reference/timestream/misc.md

@@ -13,4 +13,5 @@
     Timestream.if_
     Timestream.lag
     Timestream.null_if
+    Timestream.pipe
 ```

python/docs/source/reference/timestream/records.md

@@ -1,7 +1,8 @@
 # Records
 
 Record operations create, extract or manipulate Timestreams of records.
-Comparison operations produce boolean Timestreams.
+
+## Record Methods
 
 ```{eval-rst}
 .. currentmodule:: kaskada

python/docs/source/reference/windows.md

@@ -6,6 +6,7 @@
 .. autosummary::
     :toctree: apidocs/windows/
 
+    Window
     Since
     Sliding
     Trailing

python/noxfile.py

@@ -31,9 +31,7 @@ def check_lint(session: nox.Session) -> None:
     session.run("flake8", *args)
     session.run("isort", "--filter-files", "--check-only", *args)
 
-    # Only do darglint and pydocstyle on pysrc (source)
-    session.run("darglint", "pysrc")
-    session.run("pydocstyle", "--convention=numpy", "pysrc")
+    session.run("pydocstyle", "--convention=google", "pysrc")
     # No way to run this as a check.
     # session.run("pyupgrade", "--py38-plus")
 

python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kaskada"
-version = "0.6.0-a.1"
+version = "0.6.0-a.2"
 description = "Kaskada query builder and local execution engine."
 requires-python = ">=3.8.1,<4.0"
 classifiers = [
@@ -23,7 +23,7 @@ plot = [
 name = "kaskada"
 description = "Kaskada query builder and local execution engine."
 authors = []
-version = "0.6.0-a.1"
+version = "0.6.0-a.2"
 
 [tool.poetry.dependencies]
 # Dependencies to install for using the project.
@@ -49,7 +49,6 @@ optional = true
 
 [tool.poetry.group.lint.dependencies]
 black = { version = ">=21.10b0", extras = ["jupyter"] }
-darglint = ">=1.8.1"
 flake8 = ">=4.0.1"
 flake8-bugbear = ">=21.9.2"
 flake8-rst-docstrings = ">=0.2.5"
@@ -81,6 +80,7 @@ optional = true
 [tool.poetry.group.docs.dependencies]
 sphinx = ">=6.0.0"
 sphinx-autobuild = ">=2021.3.14"
+sphinx-autodoc-typehints = ">=1.23.0"
 sphinx-book-theme = "^1.0.1"
 sphinx-copybutton = "^0.5.2"
 sphinx-design = "^0.5.0"

python/pysrc/kaskada/__init__.py

@@ -7,13 +7,15 @@
 from ._execution import ExecutionOptions
 from ._result import Result
 from ._session import init_session
+from ._timestream import Arg
 from ._timestream import Literal
 from ._timestream import Timestream
 from ._timestream import record
 from .udf import udf
 
 
 __all__ = [
+    "Arg",
     "ExecutionOptions",
     "init_session",
     "Literal",

python/pysrc/kaskada/_execution.py

@@ -6,18 +6,11 @@
 class ExecutionOptions:
     """Execution options for a query.
 
-    Attributes
-    ----------
-    row_limit : Optional[int]
-        The maximum number of rows to return.
-        If not specified, all rows are returned.
-
-    max_batch_size : Optional[int]
-        The maximum batch size to use when returning results.
-        If not specified, the default batch size will be used.
-
-    materialize : bool
-        If true, the query will be a continuous materialization.
+    Attributes:
+        row_limit: The maximum number of rows to return. If not specified, all rows are returned.
+        max_batch_size: The maximum batch size to use when returning results.
+          If not specified, the default batch size will be used.
+        materialize: If true, the query will be a continuous materialization.
     """
 
     row_limit: Optional[int] = None