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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy