docs(py,r): Python and R documentation with index page

.github/workflows/docs-py-quartodoc.yml

@@ -0,0 +1,75 @@
+# Workflow derived from https://github.com/posit-dev/shinychat/blob/main/.github/workflows/quartodoc.yaml
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**/*"
+      - "pkg-py/**/*"
+      - .github/workflows/docs-py-quartodoc.yml
+  pull_request:
+    paths:
+      - "docs/**/*"
+      - "pkg-py/**/*"
+      - .github/workflows/docs-py-quartodoc.yml
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: docs-py-quartodoc.yml
+
+permissions:
+  contents: write
+
+env:
+  UV_VERSION: "0.7.x"
+  PYTHON_VERSION: 3.13
+  QUARTO_VERSION: 1.7.31
+
+jobs:
+  py-docs-quartodoc:
+    runs-on: ubuntu-latest
+
+    # Only run on release events for tags start with "py/v*"
+    # if: github.event_name != 'release' || startsWith(github.ref, 'refs/tags/py/v')
+
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: 🔵 Set up Quarto
+      uses: quarto-dev/quarto-actions/setup@v2
+      with:
+        version: ${{ env.QUARTO_VERSION }}
+
+    - name: 🚀 Install uv
+      uses: astral-sh/setup-uv@v6.1.0
+      with:
+        version: ${{ env.UV_VERSION }}
+
+    - name: 🐍 Set up Python ${{ env.PYTHON_VERSION }}
+      run: uv python install ${{ env.PYTHON_VERSION }}
+
+    - name: 📦 Install package and dependencies
+      run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras --all-groups
+
+    - name: 🔌 Activate venv
+      run: |
+        source .venv/bin/activate
+        echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
+        echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
+
+    - name: 🏭 Update Python docs
+      run: |
+        make py-docs-api
+        quarto render pkg-py/docs
+
+    - name: 🚢 Deploy to GitHub pages
+      if: github.event_name != 'pull_request'
+      uses: JamesIves/github-pages-deploy-action@v4.5.0
+      with:
+        clean: false
+        folder: docs
+        branch: gh-pages

.github/workflows/docs-r-pkgdown.yml

@@ -0,0 +1,64 @@
+# Workflow derived from https://github.com/posit-dev/shinychat/blob/main/.github/workflows/pkgdown.yaml
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - 'pkg-r/man'
+      - 'pkg-r/vignettes'
+      - 'pkg-r/pkgdown'
+      - '.github/workflows/docs-r-pkgdown.yml'
+  pull_request:
+    paths:
+      - 'pkg-r/man'
+      - 'pkg-r/vignettes'
+      - 'pkg-r/pkgdown'
+      - '.github/workflows/docs-r-pkgdown.yml'
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: docs-r-pkgdown.yml
+
+permissions:
+  contents: write
+
+jobs:
+  r-docs-pkgdown:
+    runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+
+    # Only run on release events for tags start with "r/v*"
+    # if: github.event_name != 'release' || startsWith(github.ref, 'refs/tags/r/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+          working-directory: pkg-r
+
+      - name: Build site
+        run: make r-docs
+
+      - name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs

.github/workflows/py-release.yml

@@ -31,7 +31,7 @@ jobs:
         run: uv python install ${{ env.PYTHON_VERSION }}
 
       - name: 📦 Install the project
-        run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras
+        run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras --all-groups
 
       #   - name: 🧪 Check tests
       #     run: make py-check-tests

.github/workflows/py-test.yml

@@ -35,7 +35,7 @@ jobs:
         run: uv python install ${{matrix.config.python-version }}
 
       - name: 📦 Install the project
-        run: uv sync --python ${{matrix.config.python-version }} --all-extras
+        run: uv sync --python ${{matrix.config.python-version }} --all-extras --all-groups
 
       #   - name: 🧪 Check tests
       #     run: make py-check-tests

.gitignore

@@ -5,6 +5,12 @@ README.html
 .DS_Store
 python-package/examples/titanic.db
 .quarto
+*.db
+
+docs/r
+docs/py
+
+!pkg-py/docs
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -237,7 +243,7 @@ vignettes/*.pdf
 .Renviron
 
 # pkgdown site
-docs/
+#docs/
 
 # translation temp files
 po/*~
@@ -247,3 +253,5 @@ rsconnect/
 
 uv.lock
 _dev
+
+/.quarto/

Makefile

@@ -7,21 +7,21 @@ PATH_PKG_R := pkg-r
 PATH_PKG_PY := pkg-py
 PATH_PKG_JS := js
 
-# .PHONY: install-quarto
-# install-quarto:
-# 	@echo "🔵 Installing quarto"
-# 	@if ! [ -z $(command -v qvm)]; then \
-# 		@echo "Error: qvm is not installed. Please visit https://github.com/dpastoor/qvm/releases/ to install it." >&2 \
-# 		exit 1; \
-# 	fi
-# 	qvm install v${QUARTO_VERSION}
-# 	@echo "🔹 Updating .vscode/settings.json"
-# 	@awk -v path="${QUARTO_PATH}" '/"quarto.path":/ {gsub(/"quarto.path": ".*"/, "\"quarto.path\": \"" path "\"")} 1' .vscode/settings.json > .vscode/settings.json.tmp && mv .vscode/settings.json.tmp .vscode/settings.json
-# 	@echo "🔹 Updating .github/workflows/quartodoc.yaml"
-# 	@awk -v ver="${QUARTO_VERSION}" '/QUARTO_VERSION:/ {gsub(/QUARTO_VERSION: .*/, "QUARTO_VERSION: " ver)} 1' .github/workflows/quartodoc.yaml > .github/workflows/quartodoc.yaml.tmp && mv .github/workflows/quartodoc.yaml.tmp .github/workflows/quartodoc.yaml
+.PHONY: install-quarto
+install-quarto:
+	@echo "🔵 Installing quarto"
+	@if ! [ -z $(command -v qvm)]; then \
+		@echo "Error: qvm is not installed. Please visit https://github.com/dpastoor/qvm/releases/ to install it." >&2 \
+		exit 1; \
+	fi
+	qvm install v${QUARTO_VERSION}
+	@echo "🔹 Updating .vscode/settings.json"
+	@awk -v path="${QUARTO_PATH}" '/"quarto.path":/ {gsub(/"quarto.path": ".*"/, "\"quarto.path\": \"" path "\"")} 1' .vscode/settings.json > .vscode/settings.json.tmp && mv .vscode/settings.json.tmp .vscode/settings.json
+	@echo "🔹 Updating .github/workflows/quartodoc.yaml"
+	@awk -v ver="${QUARTO_VERSION}" '/QUARTO_VERSION:/ {gsub(/QUARTO_VERSION: .*/, "QUARTO_VERSION: " ver)} 1' .github/workflows/quartodoc.yaml > .github/workflows/quartodoc.yaml.tmp && mv .github/workflows/quartodoc.yaml.tmp .github/workflows/quartodoc.yaml
 
-# .PHONY: docs
-# docs: r-docs-render py-docs-render ## [docs] Build the documentation
+.PHONY: docs
+docs: r-docs py-docs-render ## [docs] Build the documentation
 
 # .PHONY: docs-preview
 # docs-preview:  ## [docs] Preview the documentation
@@ -111,7 +111,7 @@ r-docs-preview: ## [r] Build R docs
 
 .PHONY: py-setup
 py-setup:  ## [py] Setup python environment
-	uv sync --all-extras
+	uv sync --all-extras --all-groups
 
 .PHONY: py-check
 # py-check:  py-check-format py-check-types py-check-tests ## [py] Run python checks
@@ -165,39 +165,39 @@ py-format: ## [py] Format python code
 # 	@echo "📸 Updating pytest snapshots"
 # 	uv run pytest --snapshot-update
 
-# .PHONY: py-docs
-# py-docs: py-docs-api py-docs-render ## [py] Build python docs
-
-# .PHONY: py-docs-render
-# py-docs-render:  ## [py] Render python docs
-# 	@echo "📖 Rendering python docs with quarto"
-# 	@$(eval export IN_QUARTODOC=true)
-# 	${QUARTO_PATH} render pkg-py/docs
-
-# .PHONY: py-docs-preview
-# py-docs-preview:  ## [py] Preview python docs
-# 	@echo "📖 Rendering python docs with quarto"
-# 	@$(eval export IN_QUARTODOC=true)
-# 	${QUARTO_PATH} preview pkg-py/docs
-
-# .PHONY: py-docs-api
-# py-docs-api:  ## [py] Update python API docs
-# 	@echo "📖 Generating python docs with quartodoc"
-# 	@$(eval export IN_QUARTODOC=true)
-# 	cd pkg-py/docs && uv run quartodoc build
-# 	cd pkg-py/docs && uv run quartodoc interlinks
-
-# .PHONY: py-docs-api-watch
-# py-docs-api-watch:  ## [py] Update python docs
-# 	@echo "📖 Generating python docs with quartodoc"
-# 	@$(eval export IN_QUARTODOC=true)
-# 	uv run quartodoc build --config pkg-py/docs/_quarto.yml --watch
-
-# .PHONY: py-docs-clean
-# py-docs-clean:   ## [py] Clean python docs
-# 	@echo "🧹 Cleaning python docs"
-# 	rm -r pkg-py/docs/api
-# 	find pkg-py/docs/py -name '*.quarto_ipynb' -delete
+.PHONY: py-docs
+py-docs: py-docs-api py-docs-render ## [py] Build python docs
+
+.PHONY: py-docs-render
+py-docs-render:  ## [py] Render python docs
+	@echo "📖 Rendering python docs with quarto"
+	@$(eval export IN_QUARTODOC=true)
+	${QUARTO_PATH} render pkg-py/docs
+
+.PHONY: py-docs-preview
+py-docs-preview:  ## [py] Preview python docs
+	@echo "📖 Rendering python docs with quarto"
+	@$(eval export IN_QUARTODOC=true)
+	${QUARTO_PATH} preview pkg-py/docs
+
+.PHONY: py-docs-api
+py-docs-api:  ## [py] Update python API docs
+	@echo "📖 Generating python docs with quartodoc"
+	@$(eval export IN_QUARTODOC=true)
+	cd pkg-py/docs && uv run quartodoc build
+	cd pkg-py/docs && uv run quartodoc interlinks
+
+.PHONY: py-docs-api-watch
+py-docs-api-watch:  ## [py] Update python docs
+	@echo "📖 Generating python docs with quartodoc"
+	@$(eval export IN_QUARTODOC=true)
+	uv run quartodoc build --config pkg-py/docs/_quarto.yml --watch
+
+.PHONY: py-docs-clean
+py-docs-clean:   ## [py] Clean python docs
+	@echo "🧹 Cleaning python docs"
+	rm -r pkg-py/docs/api
+	find pkg-py/docs/py -name '*.quarto_ipynb' -delete
 
 .PHONY: py-build
 py-build:   ## [py] Build python package