docs: Some doc tweaks (#610)

Get the type alias to render, along with links. Rename the type alias to `Literal` and use it just for the literals.
kaskada-ai · Aug 7, 2023 · a1e1ca8 · a1e1ca8
1 parent 8e2b748
commit a1e1ca8
Show file tree

Hide file tree

Showing 8 changed files with 158 additions and 150 deletions.
diff --git a/sparrow-py/README.md b/sparrow-py/README.md
@@ -14,7 +14,7 @@ It is built on Apache Arrow, using the same columnar execution strategy that mak
 
 ## Install Python
 
-Use `pyenv` and install at least `3.7` or `3.8`.
+Use `pyenv` and install at least `3.8` (most development occurs under `3.11`).
 If multiple versions are installed, `nox` will test against each of them.
 
 ## Building and Testing

diff --git a/sparrow-py/docs/source/conf.py b/sparrow-py/docs/source/conf.py
@@ -2,6 +2,13 @@
 from typing import Any
 from typing import Dict
 
+import os
+import sys
+sys.path[0] = os.path.abspath(os.path.join("..", "..", "pysrc", "sparrow_py"))
+print(sys.path)
+
+import sparrow_py
+
 project = "sparrow-py"
 author = "Kaskada Contributors"
 copyright = "2023, Kaskada Contributors"
@@ -30,7 +37,7 @@
     "use_edit_page_button": True,
     "use_issues_button": True,
     "repository_branch": "main",
-    "path_to_docs": "sparrow-py/docs/",
+    "path_to_docs": "sparrow-py/docs/source",
     "icon_links": [
         {
             "name": "GitHub",
@@ -55,7 +62,7 @@
     "github_user": "kaskada-ai",
     "github_repo": "kaskada",
     "github_version": "main",
-    "doc_path": "sparrow-py/docs/",
+    "doc_path": "sparrow-py/docs/source",
 }
 
 intersphinx_mapping: Dict[str, Any] = {
@@ -92,6 +99,6 @@
 # Don't show class signature with the class' name.
 autodoc_class_signature = "separated"
 
-autodoc_type_aliases = { 'Arg': 'sparrow_py.Arg' }
-
 autosummary_generate = True
+
+napoleon_preprocess_types = True
diff --git a/sparrow-py/docs/source/index.md b/sparrow-py/docs/source/index.md
@@ -4,11 +4,21 @@ hide-toc: true
 
 # Kaskada Timestreams
 
-```{include} ../README.md
+```{include} ../../README.md
 :start-after: <!-- start elevator-pitch -->
 :end-before: <!-- end elevator-pitch -->
 ```
 
+## What are "Timestreams"?
+A [Timestream](reference/timestream/index) describes how a value changes over time. In the same way that SQL
+queries transform tables and graph queries transform nodes and edges,
+Kaskada queries transform Timestreams.
+
+In comparison to a timeseries which often contains simple values (e.g., numeric
+observations) defined at fixed, periodic times (i.e., every minute), a Timestream
+contains any kind of data (records or collections as well as primitives) and may
+be defined at arbitrary times corresponding to when the events occur.
+
 ## Getting Started with Timestreams
 
 Getting started with Timestreams is as simple as `pip` installing the Python library, loading some data and running a query.
@@ -25,16 +35,6 @@ data = t.sources.Parquet.from_file(
 data.count().run().to_pandas()
 ```
 
-## What are "Timestreams"?
-A [Timestream](reference/timestream/index) describes how a value changes over time. In the same way that SQL
-queries transform tables and graph queries transform nodes and edges,
-Kaskada queries transform Timestreams.
-
-In comparison to a timeseries which often contains simple values (e.g., numeric
-observations) defined at fixed, periodic times (i.e., every minute), a Timestream
-contains any kind of data (records or collections as well as primitives) and may
-be defined at arbitrary times corresponding to when the events occur.
-
 ```{toctree}
 :hidden:
 

diff --git a/sparrow-py/docs/source/reference/timestream/index.md b/sparrow-py/docs/source/reference/timestream/index.md
@@ -1,17 +1,11 @@
 # Timestream
 
-```{todo}
-- [ ] Expand the `Arg` type alias in timestreams accordingly.
-```
-
 ```{eval-rst}
 .. currentmodule:: sparrow_py
 
-.. autoclass:: Timestream
-    :members:
-    :noindex:
-    :autosummary:
-    :autosummary-nosignatures:
+.. autoclass:: sparrow_py.Literal
+.. autoclass:: sparrow_py.Timestream
+    :exclude-members: __init__
 ```
 
 ```{toctree}

diff --git a/sparrow-py/poetry.lock b/sparrow-py/poetry.lock
diff --git a/sparrow-py/pyproject.toml b/sparrow-py/pyproject.toml
@@ -7,6 +7,8 @@ authors = []
 [tool.poetry.dependencies]
 pandas = "^2.0.3"
 python = ">=3.8,<4.0"
+pyarrow = "^12.0.1"
+typing-extensions = "^4.7.1"
 
 [tool.poetry.dev-dependencies]
 maturin = "^1.1.0"
@@ -20,19 +22,21 @@ isort = ">=5.10.1"
 mypy = ">=0.930"
 pandas-stubs = "^2.0.2"
 pep8-naming = ">=0.12.1"
-pyarrow = "^12.0.1"
 pydocstyle = "^6.3.0"
 pytest = ">=6.2.5"
 pyupgrade = ">=2.29.1"
 safety = ">=1.10.3"
-sphinx = ">=4.3.2"
+sphinx = ">=6.0.0"
 sphinx-autobuild = ">=2021.3.14"
 sphinx-book-theme = "^1.0.1"
 sphinx-copybutton = "^0.5.2"
 typeguard = ">=2.13.3"
 xdoctest = {extras = ["colors"], version = ">=0.15.10"}
 myst-parser = {version = ">=0.16.1"}
-myst-nb = "^0.17.2"
+# Use myst-nb from git since the currently released version (0.17.2) pins
+# Sphinx to < 6. Once a new release occurs we can upgrade to `0.18.0` or newer.
+# https://github.com/executablebooks/MyST-NB/issues/530
+myst-nb = { git = "https://github.com/executablebooks/MyST-NB.git", rev = "3d6a5d1"}
 
 [tool.poetry.group.constraints]
 optional = true

diff --git a/sparrow-py/pysrc/sparrow_py/__init__.py b/sparrow-py/pysrc/sparrow_py/__init__.py
@@ -1,9 +1,11 @@
 """Kaskada query builder and local executon engine."""
+from __future__ import annotations
+
 from . import sources
 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 ._windows import SinceWindow
@@ -12,14 +14,14 @@
 
 
 __all__ = [
-    "Arg",
     "ExecutionOptions",
-    "Timestream",
     "init_session",
+    "Literal",
     "record",
     "Result",
     "SinceWindow",
     "SlidingWindow",
     "sources",
+    "Timestream",
     "Window",
 ]