Great Docs

.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:posit-dev.github.io)"
+    ]
+  }
+}

.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: CI Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-docs:
+    name: "Build Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Full history for accurate page timestamps
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: docs
+          cache-on-failure: true
+
+      - name: Install package and dependencies
+        run: |
+          python -m pip install uv
+          uv sync --group docs
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Build docs
+        run: uv run great-docs build
+
+      - name: Save docs artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+  publish-docs:
+    name: "Publish Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: great-docs/_site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -29,3 +29,11 @@ ENV/
 env.bak/
 venv.bak/
 .venv/
+
+# Great Docs build directory (ephemeral, do not commit)
+great-docs/
+
+# Great Docs versioned-build artifacts
+.great-docs-build/
+.great-docs-cache/
+.great-docs/

great-docs.yml

@@ -0,0 +1,117 @@
+# Great Docs Configuration
+# See https://posit-dev.github.io/great-docs/user-guide/03-configuration.html
+
+# Module Name (optional)
+# ----------------------
+# Set this if your importable module name differs from the project name.
+# Example: project 'py-yaml12' with module name 'yaml12'
+module: ggsql
+
+# Docstring Parser
+# ----------------
+# The docstring format used in your package (numpy, google, or sphinx)
+parser: numpy
+
+# Dynamic Introspection
+# ---------------------
+# Use runtime introspection for more accurate documentation (default: true)
+# Set to false if your package has cyclic alias issues (e.g., PyO3/Rust bindings)
+dynamic: true
+
+# Repo
+# ----
+repo: https://github.com/posit-dev/ggsql-python
+
+# API Discovery Settings
+# ----------------------
+# Exclude items from auto-documentation
+# exclude:
+#   - InternalClass
+#   - helper_function
+
+# Logo & Favicon
+# ---------------
+# Point to a single logo file (replaces the text title in the navbar):
+# logo: assets/logo.svg
+#
+# For light/dark variants:
+# logo:
+#   light: assets/logo-light.svg
+#   dark: assets/logo-dark.svg
+#
+# To show the text title alongside the logo, add: show_title: true
+
+authors:
+  - name: Carson Sievert
+    role: Lead Developer
+    github: cpsievert
+
+  - name: Thomas Lin Pedersen
+    role: Contributor
+    github: thomasp85
+
+# Funding / Copyright Holder
+# --------------------------
+# Credit the organization that funds or holds copyright for this package.
+# Displays in sidebar and footer. Homepage and ROR provide links.
+funding:
+  name: "Posit Software, PBC"
+  roles:
+    - Copyright holder
+    - funder
+  homepage: https://posit.co
+  ror: https://ror.org/03wc8by49
+
+# API Reference Structure
+# -----------------------
+# Customize the sections below to organize your API documentation.
+# - Reorder items within a section to change their display order
+# - Move items between sections or create new sections
+# - Use 'members: false' to exclude methods from documentation
+# - Add 'desc:' to sections for descriptions
+
+reference:
+  - title: High-level API
+    desc: Convenience entry points for common workflows.
+    contents:
+      - render_altair
+      - validate
+      - execute
+  - title: Readers
+    desc: Execute SQL and manage DataFrames that feed visualizations.
+    contents:
+      - DuckDBReader
+  - title: Writers
+    desc: Turn a resolved Spec into rendered output.
+    contents:
+      - VegaLiteWriter
+  - title: Result types
+    desc: Objects returned from `validate()` and `reader.execute()`.
+    contents:
+      - Validated
+      - Spec
+
+# Site Settings
+# -------------
+site:
+  theme: cosmo              # Quarto theme (default: flatly)
+  toc: true                  # Show table of contents (default: true)
+  toc-depth: 2               # TOC heading depth (default: 2)
+  toc-title: On this page    # TOC title (default: "On this page")
+
+navbar_color: "#DEF1EB"
+
+# Jupyter Kernel
+# --------------
+# Jupyter kernel to use for executing code cells in .qmd files.
+# This is set at the project level so it applies to all pages, including
+# auto-generated API reference pages. Can be overridden in individual .qmd
+# file frontmatter if needed for special cases.
+jupyter: python3
+
+# CLI Documentation
+# -----------------
+# cli:
+#   enabled: true              # Enable CLI documentation
+#   module: my_package.cli     # Module containing Click commands
+#   name: cli                  # Name of the Click command object

pyproject.toml

@@ -20,6 +20,9 @@ dependencies = [
     "polars>=1.0",
 ]
 
+[project.urls]
+Repository = "https://github.com/posit-dev/ggsql-python"
+
 [project.optional-dependencies]
 test = ["pytest>=7.0", "duckdb>=1.0", "pyarrow>=14.0"]
 dev = ["maturin>=1.4"]
@@ -36,3 +39,6 @@ dev = [
     "pyarrow>=14.0",
     "pytest>=9.0.2",
 ]
+docs = [
+    "great-docs>=0.8 ; python_full_version >= '3.11'",
+]

python/ggsql/__init__.py

@@ -16,6 +16,12 @@
     execute,
 )
 
+# PyO3 classes default to __module__ = "builtins"; point them at their real
+# home so docs tooling (great-docs/griffe) can locate them.
+for _cls in (DuckDBReader, _RustVegaLiteWriter, Validated, Spec):
+    _cls.__module__ = "ggsql._ggsql"
+del _cls
+
 __all__ = [
     # Classes
     "DuckDBReader",