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)
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