Skip to content

Commit 53bdc1f

Browse files
EdwardAngertEdwardAngert
committed
docs: update documentation workflow readme with comprehensive guide
- Add clear description of workflow components and architecture - Document the two-stage PR comment system - Describe validation features in detail - Add troubleshooting section for common issues - Include section on future improvements
1 parent 6e9bad5 commit 53bdc1f

File tree

1 file changed

+150
-194
lines changed

1 file changed

+150
-194
lines changed

‎.github/docs/README.md

Lines changed: 150 additions & 194 deletions
Original file line numberDiff line numberDiff line change
@@ -52,9 +52,11 @@ brew install vale
5252
pnpm install
5353
```
5454

55-
## Workflow Architecture Overview
55+
# Coder Documentation Workflow System
5656

57-
The documentation workflow has a clear separation of concerns with multiple layers:
57+
## Workflow Architecture
58+
59+
The documentation workflow system has a clear separation of concerns with multiple layers:
5860

5961
```
6062
┌─ Workflow Entry Points ─────────────────────────────────┐
@@ -86,232 +88,186 @@ The documentation workflow has a clear separation of concerns with multiple laye
8688
└──────────────────────────────────────────────────────────┘
8789
```
8890

89-
## Available Workflows
91+
## Documentation Workflow Components
9092

91-
### Workflow Components
93+
### Entry Point Workflows
9294

93-
1. **Entry Points**:
94-
- `docs-preview.yaml`: Quick previews for PR changes
95-
- `docs-link-check.yaml`: Post-merge validation focusing on link integrity
96-
- `weekly-docs.yaml`: Scheduled comprehensive checks
97-
- `docs-ci.yaml`: Fast CI checks for formatting
95+
The system provides four specialized entry points for different validation scenarios:
9896

99-
2. **Unified Reusable Workflow**:
100-
- `docs-unified.yaml`: Central workflow with preset configurations
97+
1. **PR Preview (docs-preview.yaml)**
98+
- Triggers on PR create/update when docs files change
99+
- Performs comprehensive validation on documentation changes
100+
- Generates preview links and posts PR comments with results
101+
- Skips link checking for faster feedback
101102

102-
3. **Core Implementation**:
103-
- `docs-core/action.yaml`: Phase-based composite action
103+
2. **Post-Merge Validation (docs-link-check.yaml)**
104+
- Runs after merges to main branch
105+
- Lightweight check focused only on link integrity
106+
- Ensures merged content maintains external link validity
104107

105-
### Configuration Presets
108+
3. **Weekly Check (weekly-docs.yaml)**
109+
- Scheduled run every Monday at 9 AM
110+
- Comprehensive validation of documentation health
111+
- Checks links, cross-references, markdown structure, and formatting
112+
- Creates issues for persistent problems
106113

107-
The workflow system includes standardized configuration presets for common scenarios:
114+
4. **CI Check (docs-ci.yaml)**
115+
- Fast validation for continuous integration
116+
- Focuses on formatting and structural issues
117+
- Designed for rapid feedback
108118

109-
```yaml
110-
# Basic usage for PRs
111-
jobs:
112-
docs-check:
113-
uses: ./.github/workflows/docs-unified.yaml
114-
with:
115-
preset: 'pr' # Options: 'pr', 'post-merge', 'weekly', 'ci'
116-
```
119+
### Unified Workflow & Presets
117120

118-
Each preset configures the workflow for specific use cases:
121+
All entry points use the central `docs-unified.yaml` workflow with different preset configurations:
119122

120-
- **PR Preset**: Full validation with preview URLs and PR comments
121-
- **Post-Merge**: Link and cross-reference validation with GitHub issues
122-
- **Weekly**: Comprehensive checks with strict validation
123-
- **CI**: Rapid syntax checking with fast-fail behavior
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 |
124129

125-
### Advanced Usage
130+
These presets ensure consistent validation based on context without duplicating logic.
126131

127-
You can combine presets with explicit overrides:
132+
## Validation Features
128133

129-
```yaml
130-
jobs:
131-
docs-check:
132-
uses: ./.github/workflows/docs-unified.yaml
133-
with:
134-
preset: 'pr'
135-
check-links: false # Skip link checking for faster results
136-
notification-channels: 'slack' # Add Slack notifications
137-
```
134+
### Two-Stage PR Comment System
138135

139-
Or configure everything explicitly:
136+
The PR workflow implements a two-stage comment system:
140137

141-
```yaml
142-
jobs:
143-
docs-check:
144-
uses: ./.github/workflows/docs-unified.yaml
145-
with:
146-
# Validation options
147-
lint-markdown: true
148-
check-format: true
149-
check-links: true
150-
check-cross-references: true
151-
lint-vale: false
152-
153-
# Output options
154-
generate-preview: true
155-
post-comment: true
156-
create-issues: false
157-
fail-on-error: false
158-
159-
# Notification options
160-
notification-channels: 'github-issue'
161-
issue-labels: 'documentation,urgent'
162-
```
138+
1. **Initial Comment (Immediate)**
139+
- Posted immediately after checkout and setup
140+
- Provides preview links while validation runs
141+
- Displays a "Validation in progress" status
142+
- Allows reviewers to immediately start reviewing documentation
163143

164-
## Key Features
165-
166-
### 1. Core Requirements Implementation
167-
168-
The workflow fulfills key documentation requirements:
169-
170-
- **Single Unified Workflow**: All docs checks consolidated into one workflow
171-
- **Smart Path-Based Triggering**: Only runs on docs-related changes
172-
- **Enhanced File Detection**: Uses tj-actions/changed-files with fallbacks
173-
- **Preview Links in PR Comments**: Links to `https://coder.com/docs/@$BRANCH_NAME`
174-
- **Manifest-Aware Navigation**: Detects changes in manifest.json and provides direct file links
175-
- **Changed File Previews**: Provides direct links to files with significant changes
176-
- **Lychee Link Checking**: Comprehensive link validation including cross-references
177-
- **Vale Style Checking**: Enforces documentation style guidelines
178-
- **Efficient Post-Merge Checks**: Only runs link integrity checks after merge
179-
180-
### 2. Multi-Phase Architecture
181-
182-
The docs-core action uses a phase-based approach for optimal efficiency:
183-
184-
- **Phase 1**: Security and Configuration
185-
- Environment validation and security setup
186-
- Configuration processing with presets
187-
- Tool requirements determination
188-
- Context information extraction
189-
190-
- **Phase 2**: File Detection
191-
- Robust change detection with multiple fallback mechanisms
192-
- Cross-reference tracking for moved/renamed files
193-
- Manifest.json change detection for navigation updates
194-
195-
- **Phases 3-4**: Validation
196-
- Link checking with lychee
197-
- Vale style validation
198-
- Cross-reference integrity checking
199-
- Markdown linting and formatting validation
200-
201-
- **Phases 5-6**: Results Processing
202-
- Unified results format
203-
- Direct links to changed files in preview
204-
- Rich formatting with guidance
205-
- Always-present validation status
206-
207-
- **Phase 7**: Notifications
208-
- Multi-channel notification support
209-
- Comprehensive error reporting
210-
211-
### 3. PR Comment Features
212-
213-
When running with `post-comment: true`, the workflow posts a comprehensive PR comment containing:
214-
215-
- **Status Overview**: Summary with clear status indicators (✅, ⚠️, ❌)
216-
- **Preview Links**: Direct links to documentation preview at `https://coder.com/docs/@$BRANCH_NAME`
217-
- **Changed File Links**: Direct links to specific changed files in the preview
218-
- **Manifest Navigation**: Links to files that have been moved or changed in manifest.json
219-
- **Validation Status**: Always-present section with common commands
220-
- **Issues Section**: Detailed breakdown with fix guidance (when issues exist)
221-
222-
### 4. Unified Results Format
223-
224-
All validation results use a standardized JSON structure:
225-
226-
```json
227-
[
228-
{
229-
"name": "Markdown Linting",
230-
"status": "success|failure|warning",
231-
"message": "Summary of validation result",
232-
"guidance": "Human-readable guidance on how to fix",
233-
"fix_command": "Command to run to fix the issue"
234-
}
235-
]
236-
```
144+
2. **Updated Comment (After Validation)**
145+
- Updates the same comment with validation results
146+
- Shows comprehensive validation status
147+
- Includes direct links to changed files
148+
- Provides validation statistics and duration information
149+
150+
### Vale Style Checking
151+
152+
The workflow includes Vale style checking that:
153+
- Only examines changed files to improve performance
154+
- Validates documentation against Coder style guidelines
155+
- Runs inline in the workflow (not as a separate action)
156+
- Is configured in `.github/docs/vale/` with custom rules
157+
158+
### Link and Cross-Reference Verification
159+
160+
Link checking features:
161+
- External link validation with lychee
162+
- Internal cross-reference verification
163+
- Configurable settings and ignore patterns in `.lycheeignore`
164+
- Special handling for manifest.json navigation changes
165+
166+
### Markdown Validation
237167

238-
### 5. Performance Optimizations
168+
The workflow validates markdown:
169+
- Structural issues (headings, lists, blockquotes)
170+
- Table formatting and alignment
171+
- Basic stylistic conventions
172+
- Document structure and organization
239173

240-
- **Conditional Dependency Installation**: Only installs what's needed
241-
- **Parallel Validation**: Independent steps run concurrently
242-
- **Focused Validation**: Only runs necessary checks based on file changes
243-
- **Cross-Reference Efficiency**: Only checks relevant cross-references
244-
- **Post-Merge Optimization**: Skips redundant checks after merge to main
174+
## Workflow Configuration Options
175+
176+
Each workflow entry point can be customized with these key parameters:
177+
178+
| Parameter | Description | Default |
179+
|-----------|-------------|---------|
180+
| `preset` | Predefined configuration bundle | (required) |
181+
| `lint-markdown` | Run markdown linting | (from preset) |
182+
| `check-format` | Validate table formatting | (from preset) |
183+
| `check-links` | Verify link integrity | (from preset) |
184+
| `check-cross-references` | Check documentation cross-references | (from preset) |
185+
| `lint-vale` | Run Vale style validation | (from preset) |
186+
| `generate-preview` | Create preview links | (from preset) |
187+
| `post-comment` | Post results as PR comment | (from preset) |
188+
| `create-issues` | Create GitHub issues for failures | (from preset) |
189+
| `fail-on-error` | Fail workflow on validation errors | (from preset) |
190+
191+
## Future Improvements
192+
193+
While the current documentation workflow system is robust and efficient, there are several areas for potential future enhancements:
194+
195+
1. **Incremental Validation**
196+
- Implement only checking files that have changed since the last validation
197+
- Create a dependency graph of documentation files to optimize cross-reference checking
198+
199+
2. **Advanced Link Checking**
200+
- Add specialized handling for API endpoint references
201+
- Implement schema validation for URLs in documentation
202+
- Add validation for image references
203+
204+
3. **Better Local Integration**
205+
- Create a pre-commit hook that runs the same validation locally
206+
- Develop a VSCode extension for real-time documentation validation
207+
208+
4. **Enhanced Reporting**
209+
- Implement trending analysis of documentation issues
210+
- Add visualization of common problem areas
211+
- Create a documentation quality dashboard
212+
213+
5. **Automated Fixes**
214+
- Implement auto-correction for common documentation issues
215+
- Add AI-assisted suggestions for improvement
216+
217+
6. **Integration with External Systems**
218+
- Sync validation results with project management tools
219+
- Implement notification integrations beyond GitHub and Slack
220+
221+
By continuously improving the documentation workflow, we can maintain high-quality documentation while making the validation process more efficient for contributors.
245222

246223
## Troubleshooting
247224

248225
### Common Issues and Solutions
249226

250227
#### File Detection Problems
251228
If changed files aren't being detected correctly:
252-
- The workflow includes robust fallback mechanisms
253-
- Default files will be used when detection fails
229+
- The workflow includes fallback mechanisms to ensure validation occurs
254230
- Check workflow logs for fallback notices
231+
- Verify you have changes in the docs/ directory
255232

256233
#### Link Checking Errors
257234
If you see link checking errors:
258-
1. Run link checking locally with `lychee docs/**/*.md`
259-
2. Add legitimate failing links to `.github/docs/.lycheeignore`
260-
3. For internal cross-references, ensure anchors match headers exactly
261-
262-
#### Cross-Reference Issues
263-
When files or headings are moved/renamed:
264-
1. The workflow automatically checks for broken cross-references in:
265-
- Other documentation files
266-
- Code comments and strings throughout the codebase
267-
2. Fix any reported broken references by updating the links to point to the new location
268-
3. Use the validation results to identify which files reference the changed content
269-
270-
#### Vale Style Issues
271-
If you see Vale style warnings:
272-
1. Check specific rules in the Vale output
273-
2. Use inline comments to disable specific rules: `<!-- vale StyleName.RuleName = NO -->`
235+
- Run link checking locally: `lychee docs/**/*.md`
236+
- Add exceptions to `.github/docs/.lycheeignore` if needed
237+
- For internal cross-references, ensure anchors match headers exactly
238+
239+
#### Style Validation Issues
240+
If you encounter Vale style warnings:
241+
- Check specific rules in the output
242+
- Use inline comments to disable specific rules when appropriate:
243+
`<!-- vale StyleName.RuleName = NO -->`
244+
- Consider updating the Vale style rules if the issue occurs frequently
274245

275246
#### Preview URL Issues
276-
Preview URLs use a standardized format:
247+
The preview URL system converts branch names to URL-friendly format:
277248
- Branch names with slashes are converted to dashes
278-
- Use direct links from PR comments
279249
- Default links are provided even when no files change
250+
- The format is: `https://coder.com/docs/@<branch-name>`
280251

281-
## Usage in Other Workflows
282-
283-
If you need to incorporate documentation validation in other workflows:
284-
285-
1. **Use the Unified Workflow**:
286-
```yaml
287-
jobs:
288-
docs-validation:
289-
uses: ./.github/workflows/docs-unified.yaml
290-
with:
291-
preset: 'pr' # or other preset based on context
292-
```
293-
294-
2. **Use Configuration Presets**:
295-
- `pr`: For pull request validation with preview links
296-
- `post-merge`: For checking link integrity after merge
297-
- `weekly`: For comprehensive scheduled checks
298-
- `ci`: For fast checks during CI/CD pipelines
299-
300-
3. **Extend with Custom Options** (if needed):
301-
```yaml
302-
with:
303-
preset: 'pr'
304-
check-links: false # Disable specific checks
305-
create-issues: true # Enable additional features
306-
```
252+
## Using Documentation Validation in Custom Workflows
307253

308-
## Example Workflow Files
254+
To use documentation validation in your own workflows:
309255

310-
For reference implementation, see these workflow files:
256+
```yaml
257+
jobs:
258+
custom-docs-check:
259+
uses: ./.github/workflows/docs-unified.yaml
260+
with:
261+
preset: 'pr' # Choose a preset based on your needs
262+
# Optional overrides
263+
check-links: false # For faster checks
264+
notification-channels: 'slack' # For notifications
265+
```
311266
312-
- `docs-preview.yaml`: PR validation with preview links
313-
- `docs-link-check.yaml`: Post-merge link integrity checks
314-
- `weekly-docs.yaml`: Scheduled comprehensive validation
315-
- `docs-ci.yaml`: Fast CI checks for documentation formatting
267+
Available presets:
268+
- `pr`: Full validation with PR comments and preview links
269+
- `post-merge`: Lightweight link checking for merged content
270+
- `weekly`: Comprehensive health check for scheduled runs
271+
- `ci`: Fast validation for continuous integration
316272

317-
For detailed workflow architecture documentation, see [OPTIMIZED-WORKFLOW.md](./OPTIMIZED-WORKFLOW.md).
273+
The presets provide sensible defaults for each use case, which can be overridden as needed for specific scenarios.

0 commit comments

Comments
 (0)