Skip to content

Commit a918566

Browse files
EdwardAngertEdwardAngert
committed
feat: enhance docs workflow with cross-references and performance
- Add comprehensive cross-reference validation for internal links and images - Implement parallel processing for Vale style checks to improve performance - Create detailed architecture diagram in README for better documentation - Optimize file detection to prioritize recent changes - Add better error handling for JSON parsing
1 parent 24302a3 commit a918566

File tree

2 files changed

+469
-40
lines changed

2 files changed

+469
-40
lines changed

‎.github/docs/README.md

Lines changed: 77 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -77,33 +77,83 @@ pnpm install
7777
The documentation workflow system has a clear separation of concerns with multiple layers:
7878

7979
```
80-
┌─ Workflow Entry Points ─────────────────────────────────┐
81-
│ │
82-
│ PR Preview Post-Merge Weekly CI Check │
83-
│ Workflow Validation Checks Workflow │
84-
│ │
85-
└───────────────────┬─────────────────────────────────────┘
86-
│
87-
▼
88-
┌─ Unified Reusable Workflow ─────────────────────────────┐
89-
│ │
90-
│ docs-unified.yaml │
91-
│ - Configuration presets (PR, post-merge, weekly, CI) │
92-
│ - Conditional dependency installation │
93-
│ - Single source of truth for all validation │
94-
│ │
95-
└───────────────────┬─────────────────────────────────────┘
96-
│
97-
▼
98-
┌─ Core Implementation ────────────────────────────────────┐
99-
│ │
100-
│ docs-core/action.yaml │
101-
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
102-
│ │ File │ │ Validation │ │ Results │ │
103-
│ │ Detection │ │ & Preview │ │ Processing │ │
104-
│ └─────────────┘ └─────────────┘ └─────────────┘ │
105-
│ │
106-
└──────────────────────────────────────────────────────────┘
80+
┌─ Workflow Entry Points ───────────────────────────────────────────────────────┐
81+
│ │
82+
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌───────────┐ │
83+
│ │ PR Preview │ │ Post-Merge │ │ Weekly │ │ CI Check │ │
84+
│ │ Workflow │ │ Validation │ │ Checks │ │ Workflow │ │
85+
│ │ docs-preview.yml│ │ docs-ci.yml │ │weekly-docs.yml │ │docs-ci.yml│ │
86+
│ │ │ │ │ │ │ │ │ │
87+
│ │ • Runs on PR │ │ • Runs after │ │ • Runs weekly │ │ • Runs on │ │
88+
│ │ creation/update│ │ merges to main│ │ on schedule │ │ PR │ │
89+
│ │ • Generates │ │ • Checks links │ │ • Comprehensive │ │ • Basic │ │
90+
│ │ preview links │ │ only │ │ validation │ │ checks │ │
91+
│ │ • Validates docs│ │ • Falls back to │ │ • Creates issues│ │ • Fast │ │
92+
│ │ • Posts comments│ │ original doc │ │ for problems │ │ feedback│ │
93+
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ └─────┬─────┘ │
94+
│ │ │ │ │ │
95+
└───────────┼────────────────────┼────────────────────┼──────────────────┼───────┘
96+
│ │ │ │
97+
└──────────┬─────────┴──────────┬─────────┴──────────┬──────┘
98+
│ │ │
99+
▼ ▼ ▼
100+
┌─ Unified Reusable Workflow ─────────────────────────────────────────────────────┐
101+
│ │
102+
│ docs-unified.yaml │
103+
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
104+
│ │ Configuration System │ │
105+
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
106+
│ │ │ PR Preset │ │Post Preset │ │Weekly Preset│ │ CI Preset │ │ │
107+
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
108+
│ └───────────────────────────────────────────────────────────────────────────┘ │
109+
│ │
110+
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
111+
│ │ Conditional Setup │ │
112+
│ │ • Tool installation (Node.js, PNPM, Vale) │ │
113+
│ │ • Comment posting system │ │
114+
│ │ • Notification handling │ │
115+
│ └───────────────────────────────────────────────────────────────────────────┘ │
116+
│ │
117+
└──────────────────────────────────────┬──────────────────────────────────────────┘
118+
│
119+
▼
120+
┌─ Core Implementation (docs-core/action.yaml) ───────────────────────────────────┐
121+
│ │
122+
│ ┌─── Phase 1: Setup & Detection ───┐ ┌─── Phase 3: Validation ─────────────┐ │
123+
│ │ │ │ │ │
124+
│ │ • Configuration processing │ │ • Markdown linting │ │
125+
│ │ • Environment validation │ │ • Table format checking │ │
126+
│ │ • Changed file detection │ │ • Link validation │ │
127+
│ │ • Advanced fallback mechanisms │ │ • Vale style checking (parallel) │ │
128+
│ │ • File relevance prioritization │ │ • Enhanced cross-reference checks │ │
129+
│ └──────────────────────────────────┘ └──────────────────────────────────────┘ │
130+
│ │
131+
│ ┌─── Phase 4: Results & Reporting ──────────────────────────────────────────┐ │
132+
│ │ │ │
133+
│ │ • Results aggregation and normalization │ │
134+
│ │ • JSON-based validation tracking │ │
135+
│ │ • Two-stage PR comment system │ │
136+
│ │ • Issue reporting │ │
137+
│ │ • Statistics calculation │ │
138+
│ └───────────────────────────────────────────────────────────────────────────┘ │
139+
│ │
140+
└─────────────────────────────────────────────────────────────────────────────────┘
141+
│
142+
▼
143+
┌─ Local Development Integration ────────────────────────────────────────────────┐
144+
│ │
145+
│ Makefile targets that mirror workflow functionality: │
146+
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
147+
│ │ make lint/docs│ │make fmt/markdown│ │make lint/markdown│ │make lint/docs-style│ │
148+
│ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │
149+
│ │
150+
│ Features: │
151+
│ • Automatically detects changed files (git diff) │
152+
│ • Supports both changed-only (default) and all-files (--all) modes │
153+
│ • Uses same validation tools as GitHub Actions │
154+
│ • Provides clear error messages and fix instructions │
155+
│ │
156+
└───────────────────────────────────────────────────────────────────────────────┘
107157
```
108158

109159
## Documentation Workflow Components

0 commit comments

Comments
 (0)