Skip to content

Commit

Permalink
docs: Some doc tweaks (#610)
Browse files Browse the repository at this point in the history
Get the type alias to render, along with links. Rename the type alias to
`Literal` and use it just for the literals.
  • Loading branch information
bjchambers authored Aug 7, 2023
1 parent 8e2b748 commit a1e1ca8
Show file tree
Hide file tree
Showing 8 changed files with 158 additions and 150 deletions.
2 changes: 1 addition & 1 deletion sparrow-py/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 11 additions & 4 deletions sparrow-py/docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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",
Expand All @@ -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] = {
Expand Down Expand Up @@ -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
22 changes: 11 additions & 11 deletions sparrow-py/docs/source/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:
Expand Down
12 changes: 3 additions & 9 deletions sparrow-py/docs/source/reference/timestream/index.md
Original file line number Diff line number Diff line change
@@ -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}
Expand Down
152 changes: 78 additions & 74 deletions sparrow-py/poetry.lock

Large diffs are not rendered by default.

10 changes: 7 additions & 3 deletions sparrow-py/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand Down
8 changes: 5 additions & 3 deletions sparrow-py/pysrc/sparrow_py/__init__.py
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -12,14 +14,14 @@


__all__ = [
"Arg",
"ExecutionOptions",
"Timestream",
"init_session",
"Literal",
"record",
"Result",
"SinceWindow",
"SlidingWindow",
"sources",
"Timestream",
"Window",
]
Loading

0 comments on commit a1e1ca8

Please sign in to comment.