Skip to content

Commit a97b17b

Browse files
chendanielychendaniely
authored
docs(py,r): Initial Python and R documentation with index page (#38)
Co-authored-by: Daniel Chen <[email protected]>
1 parent 362d5db commit a97b17b

30 files changed

+1281
-307
lines changed

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Workflow derived from https://github.com/posit-dev/shinychat/blob/main/.github/workflows/quartodoc.yaml
2+
on:
3+
push:
4+
branches:
5+
- main
6+
paths:
7+
- "docs/**/*"
8+
- "pkg-py/**/*"
9+
- .github/workflows/docs-py-quartodoc.yml
10+
pull_request:
11+
paths:
12+
- "docs/**/*"
13+
- "pkg-py/**/*"
14+
- .github/workflows/docs-py-quartodoc.yml
15+
release:
16+
types: [published]
17+
workflow_dispatch:
18+
19+
name: docs-py-quartodoc.yml
20+
21+
permissions:
22+
contents: write
23+
24+
env:
25+
UV_VERSION: "0.7.x"
26+
PYTHON_VERSION: 3.13
27+
QUARTO_VERSION: 1.7.31
28+
29+
jobs:
30+
py-docs-quartodoc:
31+
runs-on: ubuntu-latest
32+
33+
# Only run on release events for tags start with "py/v*"
34+
# if: github.event_name != 'release' || startsWith(github.ref, 'refs/tags/py/v')
35+
36+
steps:
37+
- name: Check out repository
38+
uses: actions/checkout@v4
39+
with:
40+
fetch-depth: 0
41+
42+
- name: 🔵 Set up Quarto
43+
uses: quarto-dev/quarto-actions/setup@v2
44+
with:
45+
version: ${{ env.QUARTO_VERSION }}
46+
47+
- name: 🚀 Install uv
48+
uses: astral-sh/[email protected]
49+
with:
50+
version: ${{ env.UV_VERSION }}
51+
52+
- name: 🐍 Set up Python ${{ env.PYTHON_VERSION }}
53+
run: uv python install ${{ env.PYTHON_VERSION }}
54+
55+
- name: 📦 Install package and dependencies
56+
run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras --all-groups
57+
58+
- name: 🔌 Activate venv
59+
run: |
60+
source .venv/bin/activate
61+
echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
62+
echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
63+
64+
- name: 🏭 Update Python docs
65+
run: |
66+
make py-docs-api
67+
quarto render pkg-py/docs
68+
69+
- name: 🚢 Deploy to GitHub pages
70+
if: github.event_name != 'pull_request'
71+
uses: JamesIves/[email protected]
72+
with:
73+
clean: false
74+
folder: docs
75+
branch: gh-pages

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Workflow derived from https://github.com/posit-dev/shinychat/blob/main/.github/workflows/pkgdown.yaml
2+
# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
3+
on:
4+
push:
5+
branches: [main, master]
6+
paths:
7+
- 'pkg-r/man'
8+
- 'pkg-r/vignettes'
9+
- 'pkg-r/pkgdown'
10+
- '.github/workflows/docs-r-pkgdown.yml'
11+
pull_request:
12+
paths:
13+
- 'pkg-r/man'
14+
- 'pkg-r/vignettes'
15+
- 'pkg-r/pkgdown'
16+
- '.github/workflows/docs-r-pkgdown.yml'
17+
release:
18+
types: [published]
19+
workflow_dispatch:
20+
21+
name: docs-r-pkgdown.yml
22+
23+
permissions:
24+
contents: write
25+
26+
jobs:
27+
r-docs-pkgdown:
28+
runs-on: ubuntu-latest
29+
# Only restrict concurrency for non-PR jobs
30+
concurrency:
31+
group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
32+
env:
33+
GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
34+
permissions:
35+
contents: write
36+
37+
# Only run on release events for tags start with "r/v*"
38+
# if: github.event_name != 'release' || startsWith(github.ref, 'refs/tags/r/v')
39+
40+
steps:
41+
- uses: actions/checkout@v4
42+
43+
- uses: r-lib/actions/setup-pandoc@v2
44+
45+
- uses: r-lib/actions/setup-r@v2
46+
with:
47+
use-public-rspm: true
48+
49+
- uses: r-lib/actions/setup-r-dependencies@v2
50+
with:
51+
extra-packages: any::pkgdown, local::.
52+
needs: website
53+
working-directory: pkg-r
54+
55+
- name: Build site
56+
run: make r-docs
57+
58+
- name: Deploy to GitHub pages 🚀
59+
if: github.event_name != 'pull_request'
60+
uses: JamesIves/[email protected]
61+
with:
62+
clean: false
63+
branch: gh-pages
64+
folder: docs

‎.github/workflows/py-release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ jobs:
3131
run: uv python install ${{ env.PYTHON_VERSION }}
3232

3333
- name: 📦 Install the project
34-
run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras
34+
run: uv sync --python ${{ env.PYTHON_VERSION }} --all-extras --all-groups
3535

3636
# - name: 🧪 Check tests
3737
# run: make py-check-tests

‎.github/workflows/py-test.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ jobs:
3535
run: uv python install ${{matrix.config.python-version }}
3636

3737
- name: 📦 Install the project
38-
run: uv sync --python ${{matrix.config.python-version }} --all-extras
38+
run: uv sync --python ${{matrix.config.python-version }} --all-extras --all-groups
3939

4040
# - name: 🧪 Check tests
4141
# run: make py-check-tests

‎.gitignore‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@ README.html
55
.DS_Store
66
python-package/examples/titanic.db
77
.quarto
8+
*.db
9+
10+
docs/r
11+
docs/py
12+
13+
!pkg-py/docs
814

915
# Byte-compiled / optimized / DLL files
1016
__pycache__/
@@ -237,7 +243,7 @@ vignettes/*.pdf
237243
.Renviron
238244

239245
# pkgdown site
240-
docs/
246+
#docs/
241247

242248
# translation temp files
243249
po/*~
@@ -247,3 +253,5 @@ rsconnect/
247253

248254
uv.lock
249255
_dev
256+
257+
/.quarto/

‎Makefile‎

Lines changed: 48 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,21 @@ PATH_PKG_R := pkg-r
77
PATH_PKG_PY := pkg-py
88
PATH_PKG_JS := js
99

10-
# .PHONY: install-quarto
11-
# install-quarto:
12-
# @echo "🔵 Installing quarto"
13-
# @if ! [ -z $(command -v qvm)]; then \
14-
# @echo "Error: qvm is not installed. Please visit https://github.com/dpastoor/qvm/releases/ to install it." >&2 \
15-
# exit 1; \
16-
# fi
17-
# qvm install v${QUARTO_VERSION}
18-
# @echo "🔹 Updating .vscode/settings.json"
19-
# @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
20-
# @echo "🔹 Updating .github/workflows/quartodoc.yaml"
21-
# @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
10+
.PHONY: install-quarto
11+
install-quarto:
12+
@echo "🔵 Installing quarto"
13+
@if ! [ -z $(command -v qvm)]; then \
14+
@echo "Error: qvm is not installed. Please visit https://github.com/dpastoor/qvm/releases/ to install it." >&2 \
15+
exit 1; \
16+
fi
17+
qvm install v${QUARTO_VERSION}
18+
@echo "🔹 Updating .vscode/settings.json"
19+
@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
20+
@echo "🔹 Updating .github/workflows/quartodoc.yaml"
21+
@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
2222

23-
# .PHONY: docs
24-
# docs: r-docs-render py-docs-render ## [docs] Build the documentation
23+
.PHONY: docs
24+
docs: r-docs py-docs-render ## [docs] Build the documentation
2525

2626
# .PHONY: docs-preview
2727
# docs-preview: ## [docs] Preview the documentation
@@ -111,7 +111,7 @@ r-docs-preview: ## [r] Build R docs
111111

112112
.PHONY: py-setup
113113
py-setup: ## [py] Setup python environment
114-
uv sync --all-extras
114+
uv sync --all-extras --all-groups
115115

116116
.PHONY: py-check
117117
# 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
165165
# @echo "📸 Updating pytest snapshots"
166166
# uv run pytest --snapshot-update
167167

168-
# .PHONY: py-docs
169-
# py-docs: py-docs-api py-docs-render ## [py] Build python docs
170-
171-
# .PHONY: py-docs-render
172-
# py-docs-render: ## [py] Render python docs
173-
# @echo "📖 Rendering python docs with quarto"
174-
# @$(eval export IN_QUARTODOC=true)
175-
# ${QUARTO_PATH} render pkg-py/docs
176-
177-
# .PHONY: py-docs-preview
178-
# py-docs-preview: ## [py] Preview python docs
179-
# @echo "📖 Rendering python docs with quarto"
180-
# @$(eval export IN_QUARTODOC=true)
181-
# ${QUARTO_PATH} preview pkg-py/docs
182-
183-
# .PHONY: py-docs-api
184-
# py-docs-api: ## [py] Update python API docs
185-
# @echo "📖 Generating python docs with quartodoc"
186-
# @$(eval export IN_QUARTODOC=true)
187-
# cd pkg-py/docs && uv run quartodoc build
188-
# cd pkg-py/docs && uv run quartodoc interlinks
189-
190-
# .PHONY: py-docs-api-watch
191-
# py-docs-api-watch: ## [py] Update python docs
192-
# @echo "📖 Generating python docs with quartodoc"
193-
# @$(eval export IN_QUARTODOC=true)
194-
# uv run quartodoc build --config pkg-py/docs/_quarto.yml --watch
195-
196-
# .PHONY: py-docs-clean
197-
# py-docs-clean: ## [py] Clean python docs
198-
# @echo "🧹 Cleaning python docs"
199-
# rm -r pkg-py/docs/api
200-
# find pkg-py/docs/py -name '*.quarto_ipynb' -delete
168+
.PHONY: py-docs
169+
py-docs: py-docs-api py-docs-render ## [py] Build python docs
170+
171+
.PHONY: py-docs-render
172+
py-docs-render: ## [py] Render python docs
173+
@echo "📖 Rendering python docs with quarto"
174+
@$(eval export IN_QUARTODOC=true)
175+
${QUARTO_PATH} render pkg-py/docs
176+
177+
.PHONY: py-docs-preview
178+
py-docs-preview: ## [py] Preview python docs
179+
@echo "📖 Rendering python docs with quarto"
180+
@$(eval export IN_QUARTODOC=true)
181+
${QUARTO_PATH} preview pkg-py/docs
182+
183+
.PHONY: py-docs-api
184+
py-docs-api: ## [py] Update python API docs
185+
@echo "📖 Generating python docs with quartodoc"
186+
@$(eval export IN_QUARTODOC=true)
187+
cd pkg-py/docs && uv run quartodoc build
188+
cd pkg-py/docs && uv run quartodoc interlinks
189+
190+
.PHONY: py-docs-api-watch
191+
py-docs-api-watch: ## [py] Update python docs
192+
@echo "📖 Generating python docs with quartodoc"
193+
@$(eval export IN_QUARTODOC=true)
194+
uv run quartodoc build --config pkg-py/docs/_quarto.yml --watch
195+
196+
.PHONY: py-docs-clean
197+
py-docs-clean: ## [py] Clean python docs
198+
@echo "🧹 Cleaning python docs"
199+
rm -r pkg-py/docs/api
200+
find pkg-py/docs/py -name '*.quarto_ipynb' -delete
201201

202202
.PHONY: py-build
203203
py-build: ## [py] Build python package

‎docs/animation.gif‎

1.67 MB
Loading

0 commit comments

Comments
 (0)