Skip to content

Commit 65dba2c

Browse files
EdwardAngertEdwardAngert
committed
refactor: improve docs workflow with better error handling
- Streamline file detection for recently modified files - Add robust JSON parsing with error handling - Enhance error reporting for PR comments - Consolidate CI and link check workflows - Improve documentation with detailed examples - Add comprehensive Vale style rule documentation
1 parent 08dc793 commit 65dba2c

File tree

4 files changed

+314
-145
lines changed

4 files changed

+314
-145
lines changed

‎.github/docs/README.md

Lines changed: 108 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,24 @@
22

33
This directory contains GitHub Actions, configurations, and workflows for Coder's unified documentation validation system.
44

5+
## Developer Quick Start Guide
6+
7+
```bash
8+
# Check only changed documentation files (default behavior)
9+
make lint/docs
10+
11+
# Check ALL documentation files
12+
make lint/docs --all
13+
14+
# Format markdown tables and fix common issues
15+
make fmt/markdown
16+
17+
# Run Vale style check (optional, requires Vale installation)
18+
make lint/docs-style
19+
```
20+
21+
The validation system will automatically detect and check only files that have changed in your working directory. This ensures fast feedback during development.
22+
523
## Directory Structure
624

725
- `actions/docs-core`: Primary composite action with the phase-based architecture
@@ -120,15 +138,71 @@ The system provides four specialized entry points for different validation scena
120138

121139
All entry points use the central `docs-unified.yaml` workflow with different preset configurations:
122140

123-
| Preset | Description | Main Validations |
124-
|--------|-------------|------------------|
125-
| `pr` | Complete validation for PRs | markdown, formatting, style, cross-references |
126-
| `post-merge` | Lightweight check after merge | links |
127-
| `weekly` | Scheduled health check | markdown, formatting, links, cross-references |
128-
| `ci` | Fast CI validation | markdown, formatting |
141+
| Preset | Description | Main Validations | When Used |
142+
|--------|-------------|------------------|-----------|
143+
| `pr` | Complete validation for PRs | markdown, formatting, style, cross-references | PRs that modify docs (preview workflow) |
144+
| `post-merge` | Lightweight check after merge | links | After merging to main (catches broken links) |
145+
| `weekly` | Scheduled health check | markdown, formatting, links, cross-references | Weekly cron job (comprehensive check) |
146+
| `ci` | Fast CI validation | markdown, formatting | PR checks (fast feedback) |
129147

130148
These presets ensure consistent validation based on context without duplicating logic.
131149

150+
#### Preset Configuration Details
151+
152+
Each preset automatically configures the following settings:
153+
154+
**PR Preset:**
155+
```yaml
156+
lint-markdown: true # Format validation
157+
check-format: true # Table format checks
158+
check-links: true # Link validation
159+
check-xrefs: true # Cross-reference validation
160+
lint-vale: true # Style rule checking
161+
gen-preview: true # Generate preview URLs
162+
post-comment: true # Post PR comment with results
163+
create-issues: false # Don't auto-create issues
164+
fail-on-error: false # Allow preview generation even with errors
165+
```
166+
167+
**Post-Merge Preset:**
168+
```yaml
169+
lint-markdown: false # Skip format validation (already checked in PR)
170+
check-format: false # Skip table checks (already checked in PR)
171+
check-links: true # Focus on link validation after content changes
172+
check-xrefs: false # Cross-refs already checked in PR
173+
lint-vale: false # Style already checked in PR
174+
gen-preview: false # No preview needed after merge
175+
post-comment: false # No PR to comment on
176+
create-issues: false # Manual issue review after merge
177+
fail-on-error: false # Record but don't block on errors
178+
```
179+
180+
**Weekly Preset:**
181+
```yaml
182+
lint-markdown: true # Comprehensive checks
183+
check-format: true # Comprehensive checks
184+
check-links: true # Comprehensive checks
185+
check-xrefs: true # Comprehensive checks
186+
lint-vale: false # Style not critical for weekly checks
187+
gen-preview: false # No preview needed
188+
post-comment: false # No PR to comment on
189+
create-issues: true # Create issues for persistent problems
190+
fail-on-error: true # Strict validation
191+
```
192+
193+
**CI Preset:**
194+
```yaml
195+
lint-markdown: true # Focus on basic validation
196+
check-format: true # Focus on basic validation
197+
check-links: false # Skip slower checks in CI
198+
check-xrefs: false # Skip slower checks in CI
199+
lint-vale: true # Include style checks
200+
gen-preview: false # No preview in CI
201+
post-comment: false # No comments in CI
202+
create-issues: false # No issues from CI
203+
fail-on-error: true # Fail fast in CI
204+
```
205+
132206
## Validation Features
133207
134208
### Two-Stage PR Comment System
@@ -155,6 +229,34 @@ The workflow includes Vale style checking that:
155229
- Runs inline in the workflow (not as a separate action)
156230
- Is configured in `.github/docs/vale/` with custom rules
157231

232+
#### Vale Style Rules
233+
234+
The following style rules are configured:
235+
236+
| Rule | Description | Severity |
237+
|------|-------------|----------|
238+
| `Coder.Headings` | Ensures proper heading capitalization | warning |
239+
| `Coder.Terms` | Enforces consistent terminology | warning |
240+
| `Coder.RepeatedWords` | Catches repeated words like "the the" | error |
241+
| `Coder.SentenceLength` | Warns about overly long sentences | suggestion |
242+
| `GitLab.*` | Various rules from GitLab style guide | varies |
243+
244+
To suppress a Vale rule for a specific line:
245+
246+
```markdown
247+
<!-- vale Coder.SentenceLength = NO -->
248+
This is a very long sentence that would normally trigger the sentence length rule but has been explicitly exempted for a good reason such as a technical requirement or quotation.
249+
<!-- vale Coder.SentenceLength = YES -->
250+
```
251+
252+
To exempt an entire file, add this at the top:
253+
254+
```markdown
255+
---
256+
vale: false
257+
---
258+
```
259+
158260
### Link and Cross-Reference Verification
159261

160262
Link checking features:

0 commit comments

Comments
 (0)