docs: Update existing docs (#655)

Tweak wording on a few pages.
Make sure all the methods are documented.

Use poetry groups for dependencies in noxfile.

sparrow-py/docs/.gitignore

@@ -1,4 +1,4 @@
 _build
 .jupyter_cache
 jupyter_execute
-source/reference/**/api
+source/reference/apidocs

sparrow-py/docs/source/_templates/autosummary/class.rst

@@ -2,4 +2,7 @@
 
 .. currentmodule:: {{ module }}
 
-.. auto{{ objtype }}:: {{ objname }}
+.. auto{{ objtype }}:: {{ objname }}
+    :members:
+    :undoc-members:
+    :show-inheritance:

sparrow-py/docs/source/conf.py

@@ -53,6 +53,7 @@
         },
     ],
     "primary_sidebar_end": ["indices.html"],
+    "show_toc_level": 2
 }
 
 templates_path = ["_templates"]

sparrow-py/docs/source/index.md

@@ -6,32 +6,32 @@ title: Kaskada Timestreams
 
 <div class="px-4 py-5 my-5 text-center">
     <img class="d-block mx-auto mb-4" src="_static/kaskada.svg" alt="" width="auto">
-    <h1 class="display-5 fw-bold">Event-processing without the fuss.</h1>
-    <div class="col-lg-6 mx-auto">
-      <p class="lead mb-4">Real-time and historic event processing in Python.
+    <h1 class="display-5 fw-bold">Event-processing for AI applications.</h1>
+    <div class="col-lg-7 mx-auto">
+      <p class="lead mb-4">Next-generation, real-time and historic event processing.
       </p>
     </div>
 </div>
 
 ```{gallery-grid}
 :grid-columns: 1 2 2 3
 
-- header: "{fas}`timeline;pst-color-primary` Real-time processing for all events"
-  content: "Quickly process structured events so you can respond in real-time."
+- header: "{fas}`timeline;pst-color-primary` Real-time processing for all"
+  content: "Quickly process events so you can respond in real-time."
   link: ".#stream"
 - header: "{fab}`python;pst-color-primary` Python-native"
   content: "Use Python so you can load data, process it, and train and serve models from one place."
   link: ".#python"
 - header: "{fas}`gauge-high;pst-color-primary` Get started immediately"
-  content: "No infrastructure to deploy let's you jump right in."
+  content: "No infrastructure to provision let's you jump right in."
   link: ".#get-started"
 
-- header: "{fas}`rocket;pst-color-primary` Local, Remote and Distributed"
-  content: "Develop and test locally. Deploy to Docker, K8s or a service for production."
-  link: ".#local-and-distributed"
 - header: "{fas}`fast-forward;pst-color-primary` Real-time, Batch and Streaming"
   content: "Execute large-historic queries or materialize in real-time. Or both."
   link: ".#real-time-and-historic"
+- header: "{fas}`rocket;pst-color-primary` Local, Remote and Distributed"
+  content: "Develop and test locally. Deploy to Docker, K8s or a service for production."
+  link: ".#local-and-distributed"
 - header: "{fas}`backward;pst-color-primary` Time-travel"
   content: "Generate training examples from the past to predict the future."
   link: ".#time-travel"

sparrow-py/docs/source/reference/results.md

@@ -4,7 +4,7 @@
 .. currentmodule:: sparrow_py
 
 .. autosummary::
-   :toctree: api/
+   :toctree: apidocs/
 
     Result
 ```

sparrow-py/docs/source/reference/sources.md

@@ -4,8 +4,12 @@
 .. currentmodule:: sparrow_py.sources
 
 .. autosummary::
-   :toctree: api/
+   :toctree: apidocs/sources
 
-    ArrowSource
-    CsvSource
+    Source
+    CsvString
+    JsonlString
+    Pandas
+    Parquet
+    PyList
 ```

sparrow-py/docs/source/reference/timestream/aggregation.md

@@ -13,10 +13,10 @@ Windowed:
 .. currentmodule:: sparrow_py
 
 .. autosummary::
-   :toctree: api/
+   :toctree: ../apidocs/
 
-    Timestream.sum
+    Timestream.collect
     Timestream.first
     Timestream.last
-    Timestream.collect
+    Timestream.sum
 ```

sparrow-py/docs/source/reference/timestream/arithmetic.md

@@ -1,18 +1,22 @@
 # Arithmetic
 
+Timestreams support a variety of arithmetic operations.
+
+```{note}
+Note: In addition to the chainable methods, standard operators are implemented where appropriate.
+For instance, `a.add(b)` may be written as `a + b`.
+See the notes on the specific functions for more information.
+```
+
 ```{eval-rst}
 .. currentmodule:: sparrow_py
 
 .. autosummary::
-   :toctree: api/
+   :toctree: ../apidocs/
 
-    Timestream.__add__
-    Timestream.__radd__
-    Timestream.__sub__
-    Timestream.__rsub__
-    Timestream.__mul__
-    Timestream.__rmul__
-    Timestream.__truediv__
-    Timestream.__rtruediv__
+    Timestream.add
+    Timestream.sub
+    Timestream.mul
+    Timestream.div
     Timestream.neg
 ```

sparrow-py/docs/source/reference/timestream/collection.md

@@ -0,0 +1,16 @@
+# Arithmetic
+
+Timestreams allow each point to contain a collection -- a `list` or `map` -- of elements.
+
+```{eval-rst}
+.. currentmodule:: sparrow_py
+
+.. autosummary::
+   :toctree: ../apidocs/
+
+    Timestream.__getitem__
+    Timestream.flatten
+    Timestream.index
+    Timestream.length
+    Timestream.union
+```

sparrow-py/docs/source/reference/timestream/comparison.md

@@ -2,16 +2,26 @@
 
 Comparison operations produce boolean Timestreams.
 
+```{note}
+Note: In addition to the chainable methods, standard operators are implemented where appropriate.
+For instance, `a.ge(b)` may be written as `a >= b`.
+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.
+```
+
 ```{eval-rst}
 .. currentmodule:: sparrow_py
 
 .. autosummary::
-   :toctree: api/
+   :toctree: ../apidocs/
 
     Timestream.eq
+    Timestream.ge
+    Timestream.gt
+    Timestream.le
+    Timestream.lt
     Timestream.ne
-    Timestream.__gt__
-    Timestream.__ge__
-    Timestream.__lt__
-    Timestream.__le__
+    Timestream.is_null
+    Timestream.is_not_null
 ```

sparrow-py/docs/source/reference/timestream/execution.md

@@ -4,7 +4,7 @@
 .. currentmodule:: sparrow_py
 
 .. autosummary::
-   :toctree: api/
+   :toctree: ../apidocs/
 
     Timestream.preview
     Timestream.run

sparrow-py/docs/source/reference/timestream/grouping.md

@@ -0,0 +1,11 @@
+# Grouping
+
+```{eval-rst}
+.. currentmodule:: sparrow_py
+
+.. autosummary::
+   :toctree: ../apidocs/
+
+    Timestream.lookup
+    Timestream.with_key
+```

sparrow-py/docs/source/reference/timestream/index.md

@@ -14,9 +14,12 @@
 
 aggregation
 arithmetic
+collection
 comparison
 execution
+grouping
 logical
 misc
 records
+time
 ```

sparrow-py/docs/source/reference/timestream/logical.md

@@ -4,7 +4,7 @@
 .. currentmodule:: sparrow_py
 
 .. autosummary::
-   :toctree: api/
+   :toctree: ../apidocs/
 
     Timestream.and_
     Timestream.or_

sparrow-py/docs/source/reference/timestream/misc.md

@@ -4,7 +4,12 @@
 .. currentmodule:: sparrow_py
 
 .. autosummary::
-   :toctree: api/
+   :toctree: ../apidocs/
 
+    Timestream.cast
     Timestream.data_type
+    Timestream.filter
+    Timestream.if_
+    Timestream.lag
+    Timestream.null_if
 ```

sparrow-py/docs/source/reference/timestream/records.md

@@ -7,11 +7,12 @@ Comparison operations produce boolean Timestreams.
 .. currentmodule:: sparrow_py
 
 .. autosummary::
-   :toctree: api/
+   :toctree: ../apidocs/
 
-    Timestream.__getitem__
+    Timestream.col
     Timestream.select
     Timestream.remove
     Timestream.extend
+    Timestream.record
     record
 ```

sparrow-py/docs/source/reference/timestream/time.md

@@ -0,0 +1,13 @@
+# Time
+
+```{eval-rst}
+.. currentmodule:: sparrow_py
+
+.. autosummary::
+   :toctree: ../apidocs/
+
+    Timestream.shift_by
+    Timestream.shift_to
+    Timestream.shift_until
+    Timestream.time_of
+```

sparrow-py/docs/source/reference/windows.md

@@ -1,11 +1,12 @@
 # Windows
 
 ```{eval-rst}
-.. currentmodule:: sparrow_py
+.. currentmodule:: sparrow_py.windows
 
 .. autosummary::
-    :toctree: api/
+    :toctree: apidocs/windows/
 
-    SinceWindow
-    SlidingWindow
+    Since
+    Sliding
+    Trailing
 ```