Skip to content

Commit d64cc8d

Browse files
denisecasedenisecase
committed
Prep v0.9.6
1 parent 33d6111 commit d64cc8d

14 files changed

Lines changed: 537 additions & 693 deletions

.github/workflows/ci-python-mkdocs.yml renamed to .github/workflows/ci-python-zensical.yml

Lines changed: 31 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
# ============================================================
2-
# .github/workflows/ci-python-mkdocs.yml (Continuous Integration)
2+
# .github/workflows/ci-python-zensical.yml (Continuous Integration)
33
# ============================================================
44
# SOURCE: https://github.com/denisecase/templates
55
#
66
# WHY-FILE: Validate repository hygiene, python, and documentation builds.
7-
# REQ: Any check that can be run locally MUST be available locally via pre-commit.
87
# REQ: CI MUST NOT introduce arbitrary rules that are not reproducible locally.
9-
# OBS: CI validates only; it never edits files or deploys docs.
8+
# OBS: CI validates only; it should not edit files or deploy docs.
109

11-
name: CI (Python + MkDocs)
10+
name: CI (Python + Zensical)
1211

1312
# WHY: Validate code, docs, and repo metadata on PRs and pushes.
1413
# OBS: This workflow validates only; it never deploys.
@@ -29,9 +28,11 @@ env:
2928

3029
jobs:
3130
ci:
32-
name: Repository / Python checks and MkDocs build
31+
name: Repository / Python checks and Zensical build
3332
runs-on: ubuntu-latest # WHY: Linux environment matches most production deployments
3433
timeout-minutes: 30 # WHY: Prevent hanging jobs. If over time, it is likely stuck.
34+
env:
35+
UV_PYTHON: "3.14" # WHY: Set Python version for all steps.
3536

3637
steps:
3738
# ============================================================
@@ -42,81 +43,64 @@ jobs:
4243
# WHY: Needed to access files for checks.
4344
uses: actions/checkout@v6
4445

45-
- name: A2) Run pre-commit (all files)
46-
# WHY: Single source of truth for locally runnable quality gates.
47-
# OBS: Fails if hooks would modify files; does not commit changes.
48-
id: precommit # WHY: Identify step for conditional follow-up.
49-
uses: pre-commit/action@v3.0.1
50-
with:
51-
extra_args: --all-files
52-
53-
- name: A2f) If pre-commit failed, run it locally
54-
if: failure()
55-
run: |
56-
echo "## Pre-commit failed" >> "$GITHUB_STEP_SUMMARY"
57-
echo "Please run pre-commit locally and commit the resulting changes." >> "$GITHUB_STEP_SUMMARY"
58-
59-
- name: A3) Install uv (with caching)
46+
- name: A2) Install uv (with caching and uv.lock awareness)
6047
uses: astral-sh/setup-uv@v7
6148
with:
6249
enable-cache: true # WHY: Speed up installs on subsequent runs
6350
cache-dependency-glob: "uv.lock" # WHY: Only re-cache when dependencies change
6451

65-
- name: A4) Install Python 3.14
52+
- name: A3) Install Python 3.14 (no repo changes needed)
6653
run: uv python install 3.14
6754

55+
- name: A4) Sync to install all dependencies
56+
run: uv sync --extra dev --extra docs --upgrade
57+
6858
- name: A5) Show tool versions
6959
run: |
70-
python --version
7160
uv --version
61+
uv run python --version
62+
if [ -f "zensical.toml" ]; then
63+
uv run zensical --version
64+
fi
7265
73-
- name: A6) Sync to install all dependencies
74-
run: uv sync --extra dev --extra docs --upgrade
66+
- name: A6) Run pre-commit (all files)
67+
run: uv tool run pre-commit run --all-files
7568

7669
# ============================================================
7770
# === BASELINE CHECKS ===
7871
# ============================================================
7972

80-
- name: B1) validate-pyproject (must be in pyproject.toml deps)
73+
- name: B1) validate-pyproject (must be in pyproject.toml dependencies)
8174
run: uv run validate-pyproject pyproject.toml
8275

83-
- name: B2) Ruff format (check only; no fixes)
84-
run: uv run ruff format --check --diff .
85-
86-
- name: B3) Ruff lint (no fixes)
87-
run: uv run ruff check .
88-
8976
# ============================================================
9077
# === COVERAGE AND TESTS: Verify functionality ===
9178
# ============================================================
9279

9380
- name: C1) Run pytest with coverage
9481
run: |
95-
if [ -d "tests" ] && [ -n "$(find tests -name 'test_*.py' -o -name '*_test.py')" ]; then
82+
if [ -d "tests" ] && [ -n "$(find tests -type f \( -name 'test_*.py' -o -name '*_test.py' \) -print -quit)" ]; then
9683
uv run pytest --verbose --cov=src --cov-report=term-missing --cov-report=xml
9784
else
98-
echo "No tests found - creating empty coverage report"
99-
echo "## No Tests Found" >> $GITHUB_STEP_SUMMARY
100-
echo "Please add test files to the tests/ directory." >> $GITHUB_STEP_SUMMARY
101-
# Create empty coverage file so artifact upload doesn't fail
102-
echo '<?xml version="1.0" ?><coverage></coverage>' > coverage.xml
85+
echo "## No Tests Found" >> "$GITHUB_STEP_SUMMARY"
86+
echo "Tests directory missing or empty. CI continues." >> "$GITHUB_STEP_SUMMARY"
10387
fi
10488
10589
- name: C2) Upload test coverage to GitHub Summary
10690
if: always()
10791
run: |
108-
echo "## Test Coverage Report" >> $GITHUB_STEP_SUMMARY
92+
echo "## Test Coverage Report" >> "$GITHUB_STEP_SUMMARY"
10993
if [ -f ".coverage" ]; then
110-
echo '```' >> $GITHUB_STEP_SUMMARY
111-
uv run coverage report >> $GITHUB_STEP_SUMMARY
112-
echo '```' >> $GITHUB_STEP_SUMMARY
94+
echo '```' >> "$GITHUB_STEP_SUMMARY"
95+
uv run coverage report >> "$GITHUB_STEP_SUMMARY"
96+
echo '```' >> "$GITHUB_STEP_SUMMARY"
11397
else
114-
echo "No coverage data available." >> $GITHUB_STEP_SUMMARY
98+
echo "No coverage data available." >> "$GITHUB_STEP_SUMMARY"
11599
fi
116100
117101
- name: C3) Upload coverage artifact
118102
if: always() && hashFiles('coverage.xml') != ''
119-
uses: actions/upload-artifact@v6
103+
uses: actions/upload-artifact@v7
120104
with:
121105
name: coverage-report
122106
path: coverage.xml
@@ -126,11 +110,10 @@ jobs:
126110
# === DEPLOY: Build only, don't deploy yet ===
127111
# ============================================================
128112

129-
- name: D1) Build docs (mkdocs --strict)
130-
id: build-docs
113+
- name: D1) Build docs with Zensical
131114
run: |
132-
if [ -f "mkdocs.yml" ] || [ -f "mkdocs.yaml" ]; then
133-
uv run mkdocs build --strict --verbose
115+
if [ -f "zensical.toml" ]; then
116+
uv run zensical build
134117
else
135-
echo "No mkdocs config found; skipping docs build."
118+
echo "No zensical.toml config found; skipping docs build."
136119
fi

‎.github/workflows/deploy-mkdocs.yml‎

Lines changed: 0 additions & 91 deletions
This file was deleted.

‎.github/workflows/deploy-zensical.yml‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# ============================================================
2+
# .github/workflows/deploy-zensical.yml (Deploy Docs)
3+
# ============================================================
4+
# SOURCE: https://github.com/denisecase/templates
5+
#
6+
# WHY-FILE: Build and deploy documentation to GitHub Pages on pushes to main.
7+
# REQ: Repo Settings -> Pages -> Build and deployment -> Source:
8+
# GitHub Actions
9+
10+
name: Docs Deploy (Zensical)
11+
12+
on:
13+
push:
14+
branches: [main] # WHY: Run when pushing to main branch.
15+
workflow_dispatch: # WHY: Allow manual triggering from Actions tab.
16+
17+
permissions:
18+
contents: read # WHY: Needed to checkout code.
19+
pages: write # WHY: Required to deploy to GitHub Pages.
20+
id-token: write # WHY: Required by deploy-pages for OIDC.
21+
22+
env:
23+
PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
24+
PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
25+
26+
concurrency:
27+
# WHY: Only one Pages deployment at a time per branch.
28+
group: pages-${{ github.ref }}
29+
cancel-in-progress: true
30+
31+
jobs:
32+
docs:
33+
name: Deploy Documentation site
34+
runs-on: ubuntu-latest
35+
timeout-minutes: 30 # WHY: Prevent hanging jobs. If over, it is likely stuck.
36+
env:
37+
UV_PYTHON: "3.14" # WHY: Set Python version for all steps.
38+
39+
steps:
40+
# ============================================================
41+
# ASSEMBLE: Get code and set up environment
42+
# ============================================================
43+
44+
- name: A1) Checkout repository code
45+
# WHY: Needed to access files for checks.
46+
uses: actions/checkout@v6
47+
48+
- name: A2) Configure GitHub Pages
49+
# WHY: Sets Pages metadata for deployments.
50+
uses: actions/configure-pages@v5
51+
52+
- name: A3) Install uv (with caching and uv.lock awareness)
53+
uses: astral-sh/setup-uv@v7
54+
with:
55+
enable-cache: true # WHY: Speed up installs on subsequent runs
56+
cache-dependency-glob: "uv.lock" # WHY: Only re-cache when dependencies change
57+
58+
- name: A4) Install Python 3.14 (no repo changes needed)
59+
run: uv python install 3.14
60+
61+
- name: A5) Sync to install all dependencies
62+
run: uv sync --extra dev --extra docs --upgrade
63+
64+
- name: A6) Show tool versions
65+
run: |
66+
uv --version
67+
uv run python --version
68+
if [ -f "zensical.toml" ]; then
69+
uv run zensical --version
70+
fi
71+
72+
# ============================================================
73+
# === DEPLOY: Build and deploy ===
74+
# ============================================================
75+
76+
- name: D1) Build docs with Zensical
77+
run: |
78+
if [ ! -f "zensical.toml" ]; then
79+
echo "zensical.toml not found; refusing to deploy." >> "$GITHUB_STEP_SUMMARY"
80+
exit 1
81+
fi
82+
uv run zensical build
83+
84+
- name: D2) Verify site output exists
85+
# WHY: Zensical should create a static site in the configured output directory
86+
# (commonly "site/"). If the directory does not exist, the documentation
87+
# build likely failed or the configuration is incorrect.
88+
run: |
89+
if [ ! -d "site" ]; then
90+
echo "## Documentation build output missing" >> "$GITHUB_STEP_SUMMARY"
91+
echo "Expected directory 'site/' was not created." >> "$GITHUB_STEP_SUMMARY"
92+
echo "Check the Zensical build step and zensical.toml configuration." >> "$GITHUB_STEP_SUMMARY"
93+
exit 1
94+
fi
95+
96+
- name: D3) Upload Pages artifact
97+
# WHY: GitHub Pages deployments require a packaged artifact containing
98+
# the built static site. This step bundles the contents of the site/
99+
# directory so the next step can publish it.
100+
uses: actions/upload-pages-artifact@v4
101+
with:
102+
path: site # WHY: Default Zensical output directory for the built site.
103+
104+
- name: D4) Deploy to GitHub Pages
105+
# WHY: This step takes the uploaded artifact and publishes it to
106+
# GitHub Pages so the documentation becomes publicly accessible.
107+
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)