Docs infra

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Build documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build documentation
+        run: uv run --extra docs zensical build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/lint.yml

@@ -40,4 +40,4 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Run pre-commit (with uvx)
-        run: uvx pre-commit run --all-files
+        run: uvx pre-commit run --all-files --verbose

.gitignore

@@ -12,3 +12,5 @@ test_data
 .chainlink
 .claude
 CHANGELOG.md
+*.ipynb
+/site

.pre-commit-config.yaml

@@ -3,6 +3,7 @@ repos:
     rev: v6.0.0
     hooks:
       - id: trailing-whitespace
+        exclude: README.md
       - id: end-of-file-fixer
       - id: check-yaml
       - id: check-added-large-files

CONTRIBUTING.md

@@ -12,31 +12,36 @@ reading [Xarray's contributing guide](https://docs.xarray.dev/en/stable/contribu
 
 ## Developer setup
 
-0. We use `uv` to manage the project: https://docs.astral.sh/uv/getting-started/installation/
+We use [uv](https://docs.astral.sh/uv/) to manage the project.
+
+0. Install uv: https://docs.astral.sh/uv/getting-started/installation/
 1. Clone the repository (bonus: [via SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account))
    and `cd xarray_sql` (the project root).
-2. Install dev dependencies via: `uv sync --dev`
-3. Install pre-commit hooks: `uv run pre-commit install`
+2. Install dev dependencies: `uv sync --dev`
+3. Install pre-commit hooks: `uvx pre-commit install`
 
-   This will automatically run code formatting (pyink) and type checking (mypy) before each commit.
-   You can also run the hooks manually with: `uv run pre-commit run --all-files`
+   This will automatically run code formatting and type checking before each commit.
+   You can also run the hooks manually with: `uvx pre-commit run --all-files`
+4. Build and serve docs locally: `uvx zensical serve`
 
 
 ## Before submitting a pull request...
 
 Thanks so much for your contribution! For a volunteer led project, we so
 appreciate your help. A few things to keep in mind:
+
 - Please be nice. We assume good intent from you, and we ask you to do the same for us.
 - Development in this project will be slow if not sporadic. Reviews will come
   as time allows.
 - Every contribution, big or small, matters and deserves credit.
 
 Here are a few requests for your development process:
+
 - We require all code to be formatted with `pyink` and type-checked with `mypy`.
   These checks run automatically via pre-commit hooks (see Developer setup above).
   If you need to run them manually:
-  - Formatting: `uv run pre-commit run pyink --all-files` or `uvx pyink .`
-  - Type checking: `uv run pre-commit run mypy --all-files` or `uv run mypy xarray_sql/`
+  - Formatting: `uvx pre-commit run pyink --all-files` or `uvx pyink .`
+  - Type checking: `uvx pre-commit run mypy --all-files` or `uvx mypy xarray_sql/`
 - Please include unit tests, if possible, and performance tests when you touch the core functionality (see `perf_tests/`).
 - It's polite to do a self review before asking for one from a maintainer. Don't stress if you forget; we all do sometimes.
 - Please add (or update) documentation when adding new code. We use [Google Style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).

docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

docs/examples.md

@@ -0,0 +1,23 @@
+# Examples
+
+```python
+import xarray as xr
+import xarray_sql as xql
+
+ds = xr.tutorial.open_dataset('air_temperature')
+
+ctx = xql.XarrayContext()
+ctx.from_dataset('air', ds, chunks=dict(time=24))
+
+result = ctx.sql('''
+  SELECT
+    "lat", "lon", AVG("air") as air_avg
+  FROM
+    "air"
+  GROUP BY
+   "lat", "lon"
+''')
+
+df = result.to_pandas()
+df.head()
+```

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/reference/xarray_sql.md

@@ -0,0 +1,8 @@
+# xarray-sql
+
+::: xarray_sql
+    options:
+      show_root_heading: true
+      show_source: false
+      members: true
+      show_submodules: true

pyproject.toml

@@ -41,6 +41,16 @@ test = [
   "xarray[io]",
   "gcsfs",
 ]
+docs = [
+    "zensical",
+    "mkdocstrings[python]",
+]
+dev = [
+    "xarray_sql[docs]",
+    "pre-commit",
+    "pytest",
+    "watchfiles",
+]
 
 [project.urls]
 Homepage = "https://github.com/alxmrs/xarray-sql"
@@ -85,6 +95,7 @@ ignore_missing_imports = true
 [dependency-groups]
 dev = [
     "xarray_sql[test]",
+    "xarray_sql[docs]",
     "py-spy>=0.4.0",
     "pyink>=24.10.1",
     "maturin>=1.9.1",