Skip to content

Commit d8d8fd0

Browse files
Copilotmmcky
Copilot
and
mmcky
committed
Implement QuantEcon Style Guide Checker GitHub Action
Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com>
1 parent b0f766b commit d8d8fd0

File tree

10 files changed

+1806
-0
lines changed

10 files changed

+1806
-0
lines changed

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

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# QuantEcon Style Guide Checker
2+
3+
An AI-enabled GitHub Action that checks lecture compliance with the QuantEcon Style Guide and provides intelligent suggestions for improvements.
4+
5+
## Features
6+
7+
- **Dual Operation Modes**: PR-triggered checks and scheduled complete reviews
8+
- **Intelligent Analysis**: Uses rule-based checking with confidence levels
9+
- **Automated Fixes**: High confidence suggestions can be auto-committed
10+
- **Comprehensive Reporting**: Detailed tables with suggestions organized by confidence
11+
- **Flexible Configuration**: Customizable paths, exclusions, and thresholds
12+
13+
## Usage
14+
15+
### PR Mode (Comment Trigger)
16+
17+
Add this to your workflow to trigger style checks when mentioned in PR comments:
18+
19+
```yaml
20+
name: Style Check on PR Comment
21+
on:
22+
issue_comment:
23+
types: [created]
24+
25+
jobs:
26+
style-check:
27+
if: github.event.issue.pull_request && contains(github.event.comment.body, '@qe-style-check')
28+
runs-on: ubuntu-latest
29+
steps:
30+
- uses: actions/checkout@v4
31+
- name: Check style guide compliance
32+
uses: QuantEcon/meta/.github/actions/qe-style-check@main
33+
with:
34+
github-token: ${{ secrets.GITHUB_TOKEN }}
35+
lectures: 'lectures'
36+
mode: 'pr'
37+
confidence-threshold: 'high'
38+
```
39+
40+
### Scheduled Mode
41+
42+
For comprehensive reviews of all lectures:
43+
44+
```yaml
45+
name: Weekly Style Check
46+
on:
47+
schedule:
48+
- cron: '0 9 * * 1' # Every Monday at 9 AM UTC
49+
workflow_dispatch:
50+
51+
jobs:
52+
style-check:
53+
runs-on: ubuntu-latest
54+
steps:
55+
- uses: actions/checkout@v4
56+
- name: Complete style guide review
57+
uses: QuantEcon/meta/.github/actions/qe-style-check@main
58+
with:
59+
github-token: ${{ secrets.GITHUB_TOKEN }}
60+
lectures: 'lectures'
61+
mode: 'scheduled'
62+
create-individual-prs: 'true'
63+
```
64+
65+
## Inputs
66+
67+
| Input | Description | Default | Required |
68+
|-------|-------------|---------|----------|
69+
| `style-guide` | Path or URL to the QuantEcon style guide document | `.github/copilot-qe-style-guide.md` | No |
70+
| `lectures` | Path to directory containing lecture documents (Myst Markdown .md files) | `lectures` | No |
71+
| `exclude-files` | Comma-separated list of file patterns to exclude (supports regex) | `` | No |
72+
| `mode` | Operation mode: "pr" for pull request mode, "scheduled" for complete review | `pr` | No |
73+
| `confidence-threshold` | Minimum confidence level for auto-commit (high, medium, low) | `high` | No |
74+
| `create-individual-prs` | Create individual PRs per lecture in scheduled mode | `false` | No |
75+
| `github-token` | GitHub token for API access | | Yes |
76+
77+
## Outputs
78+
79+
| Output | Description |
80+
|--------|-------------|
81+
| `suggestions-found` | Whether style suggestions were found (true/false) |
82+
| `high-confidence-count` | Number of high confidence suggestions |
83+
| `medium-confidence-count` | Number of medium confidence suggestions |
84+
| `low-confidence-count` | Number of low confidence suggestions |
85+
| `files-processed` | Number of files processed |
86+
| `summary-report` | Summary report of suggestions |
87+
| `detailed-report` | Detailed report with suggestions table |
88+
89+
## Style Rules Checked
90+
91+
The action checks compliance with the QuantEcon Style Guide including:
92+
93+
### Writing Conventions
94+
- **R001-R005**: General writing principles, sentence structure, capitalization
95+
- One sentence paragraphs
96+
- Proper heading capitalization
97+
- Clear and concise language
98+
99+
### Code Style
100+
- **R006-R015**: Python code formatting, variable naming, performance patterns
101+
- Unicode Greek letters (α, β, γ, etc.)
102+
- PEP8 compliance
103+
- Modern timing patterns with `qe.Timer()`
104+
105+
### Mathematical Notation
106+
- **R016-R021**: LaTeX formatting, equation numbering, symbol usage
107+
- Proper transpose notation (`\top`)
108+
- Standard matrix/vector conventions
109+
- Built-in equation numbering
110+
111+
### Figure Guidelines
112+
- **R022-R029**: Matplotlib best practices, captions, sizing
113+
- No embedded titles in plots
114+
- Proper line width settings
115+
- Lowercase axis labels
116+
117+
## Confidence Levels
118+
119+
- **High Confidence**: Clear rule violations that can be automatically fixed (e.g., Greek letter usage, transpose notation)
120+
- **Medium Confidence**: Style improvements that likely need adjustment (e.g., paragraph structure, timing patterns)
121+
- **Low Confidence**: Suggestions that may need human review (e.g., content organization, complex style choices)
122+
123+
## Examples
124+
125+
### Basic PR Check
126+
```yaml
127+
- name: Style Guide Check
128+
uses: QuantEcon/meta/.github/actions/qe-style-check@main
129+
with:
130+
github-token: ${{ secrets.GITHUB_TOKEN }}
131+
lectures: 'source/lectures'
132+
exclude-files: 'intro.md,references.md'
133+
```
134+
135+
### Scheduled Review with Individual PRs
136+
```yaml
137+
- name: Weekly Style Review
138+
uses: QuantEcon/meta/.github/actions/qe-style-check@main
139+
with:
140+
github-token: ${{ secrets.GITHUB_TOKEN }}
141+
mode: 'scheduled'
142+
create-individual-prs: 'true'
143+
confidence-threshold: 'medium'
144+
```
145+
146+
### Custom Style Guide
147+
```yaml
148+
- name: Style Check with Custom Guide
149+
uses: QuantEcon/meta/.github/actions/qe-style-check@main
150+
with:
151+
github-token: ${{ secrets.GITHUB_TOKEN }}
152+
style-guide: 'https://raw.githubusercontent.com/MyOrg/style/main/guide.md'
153+
lectures: 'content'
154+
```
155+
156+
## Integration with Existing Workflows
157+
158+
This action integrates well with:
159+
- **Documentation builds**: Run after successful builds to check style
160+
- **PR workflows**: Automatic style validation on pull requests
161+
- **Release workflows**: Ensure style compliance before releases
162+
- **Content reviews**: Regular maintenance of lecture quality
163+
164+
## Troubleshooting
165+
166+
### No Files Found
167+
- Verify the `lectures` path exists and contains `.md` files
168+
- Check `exclude-files` patterns aren't too broad
169+
- Ensure the repository structure matches the configured paths
170+
171+
### Permission Issues
172+
- Verify `github-token` has appropriate permissions
173+
- For PR creation, ensure token has `contents: write` and `pull-requests: write`
174+
- Check repository settings allow action to create PRs
175+
176+
### Style Guide Loading
177+
- If using a URL, ensure it's publicly accessible
178+
- For local files, verify the path is relative to repository root
179+
- Check that the style guide follows the expected markdown format
180+
181+
## Contributing
182+
183+
To extend or modify the style checking rules:
184+
185+
1. Update the rule definitions in `style_checker.py`
186+
2. Add corresponding tests in the test suite
187+
3. Update documentation with new rule descriptions
188+
4. Ensure confidence levels are appropriately assigned
189+
190+
See the [contribution guidelines](../../../CONTRIBUTING.md) for more details.

‎.github/actions/qe-style-check/action.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: 'QuantEcon Style Guide Checker'
2+
description: 'AI-enabled GitHub action to check lecture compliance with QuantEcon Style Guide'
3+
author: 'QuantEcon'
4+
5+
inputs:
6+
style-guide:
7+
description: 'Path or URL to the QuantEcon style guide document'
8+
required: false
9+
default: '.github/copilot-qe-style-guide.md'
10+
lectures:
11+
description: 'Path to directory containing lecture documents (Myst Markdown .md files)'
12+
required: false
13+
default: 'lectures'
14+
exclude-files:
15+
description: 'Comma-separated list of file patterns to exclude (supports regex)'
16+
required: false
17+
default: ''
18+
mode:
19+
description: 'Operation mode: "pr" for pull request mode, "scheduled" for complete review'
20+
required: false
21+
default: 'pr'
22+
confidence-threshold:
23+
description: 'Minimum confidence level for auto-commit (high, medium, low)'
24+
required: false
25+
default: 'high'
26+
create-individual-prs:
27+
description: 'Create individual PRs per lecture in scheduled mode'
28+
required: false
29+
default: 'false'
30+
github-token:
31+
description: 'GitHub token for API access'
32+
required: true
33+
34+
outputs:
35+
suggestions-found:
36+
description: 'Whether style suggestions were found (true/false)'
37+
value: ${{ steps.check.outputs.suggestions-found }}
38+
high-confidence-count:
39+
description: 'Number of high confidence suggestions'
40+
value: ${{ steps.check.outputs.high-confidence-count }}
41+
medium-confidence-count:
42+
description: 'Number of medium confidence suggestions'
43+
value: ${{ steps.check.outputs.medium-confidence-count }}
44+
low-confidence-count:
45+
description: 'Number of low confidence suggestions'
46+
value: ${{ steps.check.outputs.low-confidence-count }}
47+
files-processed:
48+
description: 'Number of files processed'
49+
value: ${{ steps.check.outputs.files-processed }}
50+
summary-report:
51+
description: 'Summary report of suggestions'
52+
value: ${{ steps.check.outputs.summary-report }}
53+
detailed-report:
54+
description: 'Detailed report with suggestions table'
55+
value: ${{ steps.check.outputs.detailed-report }}
56+
57+
runs:
58+
using: 'composite'
59+
steps:
60+
- name: Setup Python for style checking
61+
uses: actions/setup-python@v4
62+
with:
63+
python-version: '3.11'
64+
65+
- name: Install dependencies
66+
shell: bash
67+
run: |
68+
pip install requests beautifulsoup4 markdown gitpython openai
69+
70+
- name: Run style guide checker
71+
id: check
72+
shell: bash
73+
run: ${{ github.action_path }}/style-check.sh
74+
env:
75+
INPUT_STYLE_GUIDE: ${{ inputs.style-guide }}
76+
INPUT_LECTURES: ${{ inputs.lectures }}
77+
INPUT_EXCLUDE_FILES: ${{ inputs.exclude-files }}
78+
INPUT_MODE: ${{ inputs.mode }}
79+
INPUT_CONFIDENCE_THRESHOLD: ${{ inputs.confidence-threshold }}
80+
INPUT_CREATE_INDIVIDUAL_PRS: ${{ inputs.create-individual-prs }}
81+
INPUT_GITHUB_TOKEN: ${{ inputs.github-token }}
82+
GITHUB_TOKEN: ${{ inputs.github-token }}
83+
84+
branding:
85+
icon: 'check-circle'
86+
color: 'blue'

0 commit comments

Comments
 (0)