Skip to content

Commit 3b9c492

Browse files
Copilotmmcky
Copilot
and
mmcky
committed
Complete QuantEcon Style Guide Checker with documentation and examples
Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com>
1 parent d8d8fd0 commit 3b9c492

File tree

2 files changed

+241
-1
lines changed

2 files changed

+241
-1
lines changed

‎.github/actions/qe-style-check/examples.md‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# QuantEcon Style Guide Checker Examples
2+
3+
This document provides practical examples of using the QuantEcon Style Guide Checker action in different scenarios.
4+
5+
## Quick Start
6+
7+
### 1. Enable PR Style Checking
8+
9+
Add this workflow to `.github/workflows/style-check-pr.yml`:
10+
11+
```yaml
12+
name: Style Check on PR Comment
13+
on:
14+
issue_comment:
15+
types: [created]
16+
17+
jobs:
18+
style-check:
19+
if: github.event.issue.pull_request && contains(github.event.comment.body, '@qe-style-check')
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
- uses: QuantEcon/meta/.github/actions/qe-style-check@main
24+
with:
25+
github-token: ${{ secrets.GITHUB_TOKEN }}
26+
lectures: 'lectures'
27+
```
28+
29+
**Usage**: Comment `@qe-style-check` on any PR to trigger style checking.
30+
31+
### 2. Weekly Automated Review
32+
33+
Add this workflow to `.github/workflows/weekly-style-check.yml`:
34+
35+
```yaml
36+
name: Weekly Style Review
37+
on:
38+
schedule:
39+
- cron: '0 9 * * 1' # Monday 9 AM UTC
40+
41+
jobs:
42+
style-check:
43+
runs-on: ubuntu-latest
44+
steps:
45+
- uses: actions/checkout@v4
46+
- uses: QuantEcon/meta/.github/actions/qe-style-check@main
47+
with:
48+
github-token: ${{ secrets.GITHUB_TOKEN }}
49+
mode: 'scheduled'
50+
create-individual-prs: 'true'
51+
```
52+
53+
## Common Configuration Examples
54+
55+
### Custom Lecture Directory
56+
57+
```yaml
58+
- uses: QuantEcon/meta/.github/actions/qe-style-check@main
59+
with:
60+
github-token: ${{ secrets.GITHUB_TOKEN }}
61+
lectures: 'source/rst' # Custom path
62+
```
63+
64+
### Exclude Specific Files
65+
66+
```yaml
67+
- uses: QuantEcon/meta/.github/actions/qe-style-check@main
68+
with:
69+
github-token: ${{ secrets.GITHUB_TOKEN }}
70+
exclude-files: 'index.md,references.md,.*draft.*'
71+
```
72+
73+
### External Style Guide
74+
75+
```yaml
76+
- uses: QuantEcon/meta/.github/actions/qe-style-check@main
77+
with:
78+
github-token: ${{ secrets.GITHUB_TOKEN }}
79+
style-guide: 'https://raw.githubusercontent.com/MyOrg/docs/main/style.md'
80+
```
81+
82+
### Lower Confidence Threshold
83+
84+
```yaml
85+
- uses: QuantEcon/meta/.github/actions/qe-style-check@main
86+
with:
87+
github-token: ${{ secrets.GITHUB_TOKEN }}
88+
confidence-threshold: 'medium' # Auto-commit medium confidence changes
89+
```
90+
91+
## Integration Examples
92+
93+
### With Documentation Build
94+
95+
```yaml
96+
name: Build and Style Check
97+
on: [push, pull_request]
98+
99+
jobs:
100+
build:
101+
runs-on: ubuntu-latest
102+
steps:
103+
- uses: actions/checkout@v4
104+
- name: Build documentation
105+
run: jupyter-book build lectures/
106+
- name: Check style compliance
107+
uses: QuantEcon/meta/.github/actions/qe-style-check@main
108+
with:
109+
github-token: ${{ secrets.GITHUB_TOKEN }}
110+
lectures: 'lectures'
111+
```
112+
113+
### Pre-Release Style Validation
114+
115+
```yaml
116+
name: Release Preparation
117+
on:
118+
workflow_dispatch:
119+
inputs:
120+
create_release:
121+
description: 'Create release after style check'
122+
default: 'false'
123+
124+
jobs:
125+
style-check:
126+
runs-on: ubuntu-latest
127+
steps:
128+
- uses: actions/checkout@v4
129+
- name: Comprehensive style check
130+
uses: QuantEcon/meta/.github/actions/qe-style-check@main
131+
with:
132+
github-token: ${{ secrets.GITHUB_TOKEN }}
133+
mode: 'scheduled'
134+
confidence-threshold: 'low'
135+
- name: Fail if issues found
136+
if: steps.style-check.outputs.suggestions-found == 'true'
137+
run: |
138+
echo "Style issues found, cannot proceed with release"
139+
exit 1
140+
```
141+
142+
## Style Rules Reference
143+
144+
The action checks for compliance with these QuantEcon Style Guide rules:
145+
146+
### Writing (R001-R005)
147+
- **R001**: Keep it clear and keep it short
148+
- **R002**: Use one sentence paragraphs only
149+
- **R003**: Keep paragraphs short and clear
150+
- **R004**: Choose the simplest option
151+
- **R005**: Don't capitalize unless necessary
152+
153+
### Code Style (R006-R015)
154+
- **R008**: Use Unicode Greek letters (α, β, γ, etc.)
155+
- **R015**: Use `qe.Timer()` context manager
156+
157+
### Math Notation (R016-R021)
158+
- **R016**: Use `\top` for transpose
159+
- **R020**: Don't use `\tag` for manual numbering
160+
161+
### Figures (R022-R029)
162+
- **R022**: No `ax.set_title()` in matplotlib
163+
- **R028**: Use `lw=2` for line charts
164+
165+
## Troubleshooting
166+
167+
### No Files Found
168+
```yaml
169+
# Ensure correct path
170+
lectures: 'source' # Not 'source/'
171+
```
172+
173+
### Too Many Suggestions
174+
```yaml
175+
# Start with high confidence only
176+
confidence-threshold: 'high'
177+
exclude-files: 'intro.md,index.md'
178+
```
179+
180+
### Permission Errors
181+
```yaml
182+
# Ensure token has proper permissions
183+
permissions:
184+
contents: write
185+
pull-requests: write
186+
```
187+
188+
## Expected Output Examples
189+
190+
### Clean Files
191+
```
192+
✅ Excellent! All files comply with the QuantEcon Style Guide.
193+
📊 Summary: 5 files processed, no issues found.
194+
```
195+
196+
### Files with Issues
197+
```
198+
📊 Summary: 3 files processed
199+
✨ Applied 12 high confidence suggestions and committed changes to this PR.
200+
📋 Additional Suggestions:
201+
| Confidence | Count | Description |
202+
|------------|-------|-------------|
203+
| Medium | 8 | Likely improvements that may need review |
204+
| Low | 3 | Suggestions that need human review |
205+
```
206+
207+
### Detailed Report (collapsed)
208+
```
209+
📝 Detailed Style Suggestions
210+
211+
## lecture1.md
212+
### High Confidence Suggestions (4)
213+
| Line | Rule | Description | Original | Proposed |
214+
|------|------|-------------|----------|----------|
215+
| 25 | R008 | Use α instead of alpha | `alpha=0.5` | `α=0.5` |
216+
| 30 | R016 | Use \top for transpose | `A^T` | `A^\top` |
217+
```
218+
219+
This action helps maintain consistent, high-quality documentation across all QuantEcon projects!

‎test/README.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,30 @@ Each GitHub Action has its own test subdirectory:
1313
- `weekly-report/` - Tests for the `.github/actions/weekly-report` action
1414
- `test-basic.sh` - Basic functionality test for the weekly report action
1515

16+
- `qe-style-check/` - Tests for the `.github/actions/qe-style-check` action
17+
- `test-basic.sh` - Basic functionality test for the style checker
18+
- `test-lecture-with-issues.md` - Test file containing style violations
19+
- `test-lecture-clean.md` - Test file following style guidelines
20+
1621
## Running Tests
1722

1823
Tests are automatically run by the GitHub Actions workflows in `.github/workflows/`.
1924

2025
- For the `check-warnings` action, tests are run by the `test-warning-check.yml` workflow.
21-
- For the `weekly-report` action, tests are run by the `test-weekly-report.yml` workflow.
26+
- For the `weekly-report` action, tests are run by the `test-weekly-report.yml` workflow.
27+
- For the `qe-style-check` action, tests are run by the `test-qe-style-check.yml` workflow.
28+
29+
### Local Testing
30+
31+
You can run tests locally:
32+
33+
```bash
34+
# Test warning checker
35+
cd test/check-warnings && ../../.github/actions/check-warnings/action.yml
36+
37+
# Test weekly report
38+
cd test/weekly-report && ./test-basic.sh
39+
40+
# Test style checker
41+
cd test/qe-style-check && ./test-basic.sh
42+
```

0 commit comments

Comments
 (0)