Skip to content

Commit 3c72ed8

Browse files
jamesbeedyjamesbeedy
committed
fix: docs refinement
1 parent 93d648c commit 3c72ed8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+7498
-76
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# GitHub Copilot Instructions for dqlitepy
2+
3+
## Python Command Execution
4+
5+
**ALWAYS use `uv run` for Python commands in this project.**
6+
7+
This project uses `uv` for dependency management and virtual environment handling. All Python commands must be prefixed with `uv run`.
8+
9+
### Examples:
10+
11+
✅ **CORRECT:**
12+
- `uv run python script.py`
13+
14+
15+
❌ **INCORRECT:**
16+
- `python script.py`
17+
- `pytest tests/`
18+
- `python -m vantage_cli.main`
19+
- `vantage --help`
20+
- `coverage run`
21+
- `mypy .`
22+
- `black .`
23+
- `ruff check`
24+
25+
### Just Commands (Primary Development Workflow):
26+
27+
**Testing:**
28+
- `just unit` - Run unit tests with coverage (80% threshold)
29+
- `just integration` - Run integration tests
30+
- `just coverage-all` - Run full test suite with combined coverage
31+
32+
**Code Quality:**
33+
- `just typecheck` - Run static type checker (pyright)
34+
- `just lint` - Check code against style standards (codespell + ruff)
35+
- `just fmt` - Apply coding style standards (ruff format + fix)
36+
37+
**Documentation:**
38+
- `just docs-dev` - Start Docusaurus development server
39+
- `just docs-dev-port [port]` - Start dev server on specific port
40+
- `just docs-build` - Build documentation for production
41+
- `just docs-serve` - Serve built documentation
42+
- `just docs-clean` - Clean documentation build artifacts
43+
- `just docs-help` - Show documentation commands
44+
45+
**Development:**
46+
- `just lock` - Regenerate uv.lock file
47+
48+
### Installation Commands:
49+
- Install dependencies: `uv sync`
50+
- Add new dependency: `uv add package-name`
51+
- Add dev dependency: `uv add --dev package-name`
52+
- Regenerate lock: `just lock`
53+
54+
## Project Structure
55+
56+
This is a Python CLI application using:
57+
- `uv` for dependency management
58+
- `pytest` for testing
59+
- `just` for task automation
60+
- `dqlitepy` as the main package
61+
- `docusaurus` for documentation
62+
- `examples/` directory for usage patterns
63+
## Testing Patterns
64+
65+
When writing tests, ensure:
66+
1. Use `uv run pytest` to execute tests
67+
2. Place tests in the `tests/` directory
68+
3. Use fixtures for setup/teardown
69+
70+
71+
## Test Patterns
72+
73+
When working with tests, ensure:
74+
1. MockConsole includes all necessary Rich console methods
75+
3. All async functions are properly awaited in tests
76+
4. Function signatures match current implementation
77+
78+
## Never Forget
79+
80+
**EVERY Python command MUST start with `uv run`** - this is critical for proper dependency resolution and virtual environment isolation in this project.

‎.github/workflows/ci.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Helmpy Code Quality Checks
2+
on:
3+
workflow_call:
4+
pull_request:
5+
branches:
6+
- main
7+
8+
concurrency:
9+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
10+
cancel-in-progress: true
11+
12+
jobs:
13+
commitlint:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: read
17+
if: github.event_name == 'pull_request'
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0
23+
- name: Setup node
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: lts/*
27+
- name: Install commitlint
28+
run: npm install -D @commitlint/cli @commitlint/config-conventional
29+
- name: Validate PR commits with commitlint
30+
run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
31+
32+
ci-tests:
33+
name: CI-Tests
34+
runs-on: ubuntu-24.04
35+
steps:
36+
- name: Checkout
37+
uses: actions/checkout@v4
38+
- name: Install `just`
39+
run: sudo snap install just --classic
40+
- name: Install `uv`
41+
run: sudo snap install astral-uv --classic
42+
- name: Run lint checks
43+
run: just lint
44+
- name: Run type checks
45+
run: just typecheck
46+
- name: Run unit tests
47+
run: just unit

‎.github/workflows/publish.yml‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Copyright (c) 2025 Vantage Compute Corporation.
2+
name: Build and Release
3+
4+
on:
5+
push:
6+
tags:
7+
- "[0-9]+.[0-9]+.[0-9]+"
8+
- "[0-9]+.[0-9]+.[0-9]+-alpha.[0-9]+"
9+
- "[0-9]+.[0-9]+.[0-9]+-beta.[0-9]+"
10+
- "[0-9]+.[0-9]+.[0-9]+a[0-9]+"
11+
- "[0-9]+.[0-9]+.[0-9]+b[0-9]+"
12+
- "[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
13+
workflow_dispatch: # Allow manual triggering
14+
15+
permissions:
16+
contents: write # Required for creating releases
17+
id-token: write # Required for PyPI trusted publishing
18+
19+
jobs:
20+
build:
21+
name: Build Distribution
22+
runs-on: ubuntu-latest
23+
24+
steps:
25+
- name: Checkout code
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0 # Fetch full history for proper version detection
29+
30+
- name: Set up Python
31+
uses: actions/setup-python@v5
32+
with:
33+
python-version: '3.12'
34+
35+
- name: Install system dependencies
36+
run: |
37+
sudo apt-get update
38+
sudo apt-get install -y build-essential
39+
sudo snap install astral-uv --classic
40+
41+
42+
- name: Install git-cliff
43+
run: |
44+
curl -L https://github.com/orhun/git-cliff/releases/download/v2.10.0/git-cliff-2.10.0-x86_64-unknown-linux-gnu.tar.gz | tar xz
45+
sudo mv git-cliff-*/git-cliff /usr/local/bin/
46+
git-cliff --version
47+
48+
- name: Build Python package
49+
run: |
50+
uv build
51+
52+
- name: Check build artifacts
53+
run: |
54+
ls -la dist/
55+
# Basic validation - ensure files exist
56+
test -n "$(find dist -name '*.whl')" || (echo "No wheel files found" && exit 1)
57+
test -n "$(find dist -name '*.tar.gz')" || (echo "No source distribution found" && exit 1)
58+
59+
- name: Upload build artifacts
60+
uses: actions/upload-artifact@v4
61+
with:
62+
name: distribution-files
63+
path: dist/
64+
retention-days: 7
65+
66+
test-install:
67+
name: Test Installation
68+
needs: build
69+
runs-on: ubuntu-latest
70+
strategy:
71+
matrix:
72+
python-version: ['3.12', '3.13']
73+
74+
steps:
75+
- name: Set up Python ${{ matrix.python-version }}
76+
uses: actions/setup-python@v5
77+
with:
78+
python-version: ${{ matrix.python-version }}
79+
80+
- name: Download build artifacts
81+
uses: actions/download-artifact@v4
82+
with:
83+
name: distribution-files
84+
path: dist/
85+
86+
- name: Test wheel installation
87+
run: |
88+
sudo snap install astral-uv --classic
89+
uv venv
90+
uv pip install dist/*.whl
91+
uv run python3 -c "import helmpy; print('Package imported successfully')"
92+
93+
publish-pypi:
94+
name: Publish to PyPI
95+
needs: [build, test-install]
96+
runs-on: ubuntu-latest
97+
if: startsWith(github.ref, 'refs/tags/')
98+
environment:
99+
name: pypi
100+
url: https://pypi.org/p/helmpy
101+
102+
steps:
103+
- name: Download build artifacts
104+
uses: actions/download-artifact@v4
105+
with:
106+
name: distribution-files
107+
path: dist/
108+
109+
- name: Publish to PyPI
110+
run: |
111+
sudo snap install astral-uv --classic
112+
uv publish
113+
114+
create-release:
115+
name: Create GitHub Release
116+
needs: [build, test-install]
117+
runs-on: ubuntu-latest
118+
if: startsWith(github.ref, 'refs/tags/')
119+
120+
steps:
121+
- name: Checkout code
122+
uses: actions/checkout@v4
123+
with:
124+
fetch-depth: 0
125+
126+
- name: Download build artifacts
127+
uses: actions/download-artifact@v4
128+
with:
129+
name: distribution-files
130+
path: dist/
131+
132+
- name: Extract version from tag
133+
id: get_version
134+
run: |
135+
VERSION=${GITHUB_REF#refs/tags/}
136+
echo "version=$VERSION" >> $GITHUB_OUTPUT
137+
echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
138+
139+
- name: Generate release notes
140+
id: release_notes
141+
run: |
142+
# Extract release notes from CHANGELOG.md if it exists
143+
if [ -f "CHANGELOG.md" ]; then
144+
# Try to extract notes for this version using git-cliff for consistency
145+
VERSION="${{ steps.get_version.outputs.version }}"
146+
147+
# Use git-cliff to generate notes for this specific version
148+
git-cliff --latest --strip header --strip footer > release_notes.txt || true
149+
150+
# If that fails, fall back to grep method
151+
if [ ! -s release_notes.txt ]; then
152+
grep -A 1000 "^## .*${VERSION}" CHANGELOG.md | grep -B 1000 -m 2 "^## " | head -n -1 | tail -n +2 > release_notes.txt || true
153+
fi
154+
155+
# If no specific version notes found, create generic notes
156+
if [ ! -s release_notes.txt ]; then
157+
echo "Release ${{ steps.get_version.outputs.tag }}" > release_notes.txt
158+
echo "" >> release_notes.txt
159+
echo "### Changes" >> release_notes.txt
160+
echo "- See CHANGELOG.md for detailed changes" >> release_notes.txt
161+
fi
162+
else
163+
echo "Release ${{ steps.get_version.outputs.tag }}" > release_notes.txt
164+
echo "" >> release_notes.txt
165+
echo "### Files" >> release_notes.txt
166+
echo "- Source distribution (tar.gz)" >> release_notes.txt
167+
echo "- Wheel distribution (.whl)" >> release_notes.txt
168+
fi
169+
170+
echo "Release notes:"
171+
cat release_notes.txt
172+
173+
- name: Create Release
174+
uses: softprops/action-gh-release@v1
175+
with:
176+
name: Release ${{ steps.get_version.outputs.tag }}
177+
body_path: release_notes.txt
178+
files: |
179+
dist/*.tar.gz
180+
dist/*.whl
181+
draft: false
182+
prerelease: ${{ contains(steps.get_version.outputs.version, 'rc') || contains(steps.get_version.outputs.version, 'beta') || contains(steps.get_version.outputs.version, 'alpha') }}
183+
generate_release_notes: true
184+
env:
185+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
186+
187+
notify-success:
188+
name: Notify Success
189+
needs: [publish-pypi, create-release]
190+
runs-on: ubuntu-latest
191+
if: success() && startsWith(github.ref, 'refs/tags/')
192+
193+
steps:
194+
- name: Extract version from tag
195+
id: get_version
196+
run: |
197+
VERSION=${GITHUB_REF#refs/tags/}
198+
echo "version=$VERSION" >> $GITHUB_OUTPUT
199+
echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
200+
201+
- name: Success notification
202+
run: |
203+
echo "🎉 Successfully released helmpy ${{ steps.get_version.outputs.tag }}"
204+
echo "📦 Published to PyPI: https://pypi.org/project/helmpy/${{ steps.get_version.outputs.version }}/"
205+
echo "🚀 GitHub Release: ${{ github.server_url }}/${{ github.repository }}/releases/tag/${{ steps.get_version.outputs.tag }}"

0 commit comments

Comments
 (0)