mirror of
https://github.com/SoftFever/OrcaSlicer.git
synced 2026-01-04 22:07:41 -07:00
Ian Bassi
GitHub
parent
bdfae96095
commit
4b48ba1004
1 changed files with 330 additions and 0 deletions
330
.github/workflows/validate-documentation.yml
vendored
Normal file
330
.github/workflows/validate-documentation.yml
vendored
Normal file
|
|
@ -0,0 +1,330 @@
|
|||
name: Validate Documentation
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'src/slic3r/GUI/Tab.cpp'
|
||||
- 'doc/**/*.md'
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: windows-latest
|
||||
name: Check Documentation
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Get changed files
|
||||
id: changed-files
|
||||
uses: tj-actions/changed-files@v44
|
||||
with:
|
||||
files: |
|
||||
src/slic3r/GUI/Tab.cpp
|
||||
doc/**/*.md
|
||||
|
||||
- name: Run validation
|
||||
if: steps.changed-files.outputs.any_changed == 'true'
|
||||
shell: pwsh
|
||||
run: |
|
||||
# Helper Functions
|
||||
function Normalize-Fragment($fragment) {
|
||||
return $fragment.ToLower().Trim() -replace '[^a-z0-9\s-]', '' -replace ' ', '-' -replace '^-+|-+$', ''
|
||||
}
|
||||
|
||||
function Add-BrokenReference($sourceFile, $line, $target, $issue, $type) {
|
||||
return @{
|
||||
SourceFile = $sourceFile
|
||||
Line = $line
|
||||
Target = $target
|
||||
Issue = $issue
|
||||
Type = $type
|
||||
}
|
||||
}
|
||||
|
||||
function Validate-Fragment($fragment, $availableAnchors, $sourceFile, $line, $target, $type) {
|
||||
$cleanFragment = $fragment.StartsWith('#') ? $fragment.Substring(1) : $fragment
|
||||
$normalizedFragment = Normalize-Fragment $cleanFragment
|
||||
|
||||
if ($availableAnchors -notcontains $normalizedFragment) {
|
||||
return Add-BrokenReference $sourceFile $line $target "Fragment does not exist" $type
|
||||
}
|
||||
return $null
|
||||
}
|
||||
|
||||
# Initialize
|
||||
$tabFile = Join-Path $PWD "src/slic3r/GUI/Tab.cpp"
|
||||
$docDir = Join-Path $PWD 'doc'
|
||||
$brokenReferences = @()
|
||||
$docIndex = @{}
|
||||
|
||||
Write-Host "Validating documentation..." -ForegroundColor Blue
|
||||
|
||||
# Validate paths
|
||||
$hasTabFile = Test-Path $tabFile
|
||||
if (-not $hasTabFile) { Write-Host "::warning::Tab.cpp file not found at: $tabFile" }
|
||||
if (-not (Test-Path $docDir)) { Write-Host "::error::doc folder does not exist"; exit 1 }
|
||||
|
||||
# Build documentation index
|
||||
$mdFiles = Get-ChildItem -Path $docDir -Filter *.md -Recurse -File -ErrorAction SilentlyContinue
|
||||
|
||||
foreach ($mdFile in $mdFiles) {
|
||||
$baseName = [System.IO.Path]::GetFileNameWithoutExtension($mdFile.Name)
|
||||
$relPath = (Resolve-Path $mdFile.FullName).Path.Substring($docDir.Length).TrimStart('\', '/')
|
||||
$content = Get-Content -Path $mdFile.FullName -Encoding UTF8 -Raw
|
||||
$lines = Get-Content -Path $mdFile.FullName -Encoding UTF8
|
||||
|
||||
# Extract anchors
|
||||
$anchors = @()
|
||||
$anchors += [regex]::Matches($content, '(?i)<a\s+[^>]*(?:name|id)\s*=\s*[`"'']([^`"'']+)[`"'']') |
|
||||
ForEach-Object { $_.Groups[1].Value.ToLower() }
|
||||
$anchors += [regex]::Matches($content, '(?m)^#+\s+(.+)$') |
|
||||
ForEach-Object { Normalize-Fragment $_.Groups[1].Value.Trim() }
|
||||
|
||||
# Parse links
|
||||
$links = @()
|
||||
$inCodeFence = $false
|
||||
for ($i = 0; $i -lt $lines.Count; $i++) {
|
||||
$line = $lines[$i]
|
||||
if ($line.TrimStart() -match '^(```|~~~)') {
|
||||
$inCodeFence = -not $inCodeFence
|
||||
continue
|
||||
}
|
||||
if ($inCodeFence) { continue }
|
||||
|
||||
$lineForParsing = [regex]::Replace($line, '`[^`]*`', '')
|
||||
foreach ($linkMatch in [regex]::Matches($lineForParsing, '(?<!!)[^\]]*\]\(([^)]+)\)')) {
|
||||
$destRaw = $linkMatch.Groups[1].Value.Trim()
|
||||
|
||||
# Handle internal fragments
|
||||
if ($destRaw.StartsWith('#')) {
|
||||
$fragment = $destRaw.Substring(1)
|
||||
if ($fragment.Contains('#')) {
|
||||
$brokenReferences += Add-BrokenReference $relPath ($i + 1) $destRaw "Internal link must use only one #." "Link"
|
||||
} else {
|
||||
$validationResult = Validate-Fragment $fragment $anchors $relPath ($i + 1) $destRaw "Link"
|
||||
if ($validationResult) { $brokenReferences += $validationResult }
|
||||
}
|
||||
continue
|
||||
}
|
||||
|
||||
# Skip external URLs
|
||||
if ($destRaw -match '^(?:https?:|mailto:|data:|#|\\)') { continue }
|
||||
|
||||
# Check for double ##
|
||||
if ($destRaw.Contains('##')) {
|
||||
$brokenReferences += Add-BrokenReference $relPath ($i + 1) $destRaw "Use single # for fragments." "Link"
|
||||
continue
|
||||
}
|
||||
|
||||
# Parse file and fragment
|
||||
$destParts = $destRaw -split '#', 2
|
||||
$destNoFragment = $destParts[0]
|
||||
$fragment = ($destParts.Length -gt 1) ? $destParts[1] : $null
|
||||
|
||||
if ($destNoFragment) {
|
||||
$leaf = ($destNoFragment -split '[\\/]')[-1]
|
||||
if ($leaf) {
|
||||
$targetBase = $leaf.ToLower().EndsWith('.md') ? $leaf.Substring(0, $leaf.Length - 3) : $leaf
|
||||
$targetBase = $targetBase.Trim()
|
||||
if ($targetBase) {
|
||||
$linkInfo = @{
|
||||
TargetBase = $targetBase
|
||||
Fragment = $fragment
|
||||
Line = $i + 1
|
||||
SourceFile = $relPath
|
||||
}
|
||||
$links += $linkInfo
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$docIndex[$baseName] = @{ Anchors = $anchors; Links = $links }
|
||||
}
|
||||
|
||||
# Parse Tab.cpp references
|
||||
if ($hasTabFile) {
|
||||
$regex = 'optgroup->append_single_option_line\s*\(\s*(?:"([^"]+)"|([^,]+?))\s*,\s*"([^"]+)"\s*\)'
|
||||
$lines = Get-Content -Path $tabFile -Encoding UTF8
|
||||
|
||||
for ($i = 0; $i -lt $lines.Count; $i++) {
|
||||
foreach ($match in [regex]::Matches($lines[$i], $regex)) {
|
||||
$arg2Full = $match.Groups[3].Value.Trim()
|
||||
|
||||
if ($arg2Full.Contains('##')) {
|
||||
$brokenReferences += Add-BrokenReference "Tab.cpp" ($i + 1) $arg2Full "Use single # for fragments." "Link"
|
||||
continue
|
||||
}
|
||||
|
||||
$arg2Parts = $arg2Full -split '#', 2
|
||||
$docBase = $arg2Parts[0].Trim()
|
||||
$fragment = ($arg2Parts.Length -gt 1) ? $arg2Parts[1].Trim() : $null
|
||||
|
||||
if (-not $docIndex.ContainsKey($docBase)) {
|
||||
$brokenReferences += Add-BrokenReference "Tab.cpp" ($i + 1) $docBase "File does not exist" "Link"
|
||||
} elseif ($fragment) {
|
||||
$validationResult = Validate-Fragment $fragment $docIndex[$docBase].Anchors "Tab.cpp" ($i + 1) "$docBase#$fragment" "Link"
|
||||
if ($validationResult) { $brokenReferences += $validationResult }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Validate markdown links
|
||||
foreach ($baseName in $docIndex.Keys) {
|
||||
foreach ($link in $docIndex[$baseName].Links) {
|
||||
if (-not $docIndex.ContainsKey($link.TargetBase)) {
|
||||
$brokenReferences += Add-BrokenReference $link.SourceFile $link.Line "$($link.TargetBase).md" "File does not exist" "Link"
|
||||
} elseif ($link.Fragment) {
|
||||
$validationResult = Validate-Fragment $link.Fragment $docIndex[$link.TargetBase].Anchors $link.SourceFile $link.Line "$($link.TargetBase)#$($link.Fragment)" "Link"
|
||||
if ($validationResult) { $brokenReferences += $validationResult }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Validate images
|
||||
Write-Host "Validating images..." -ForegroundColor Blue
|
||||
$expectedUrlPattern = '^https://github\.com/SoftFever/OrcaSlicer/blob/main/([^?]+)\?raw=true$'
|
||||
|
||||
foreach ($file in $mdFiles) {
|
||||
$lines = Get-Content $file.FullName -Encoding UTF8
|
||||
$relPath = (Resolve-Path $file.FullName).Path.Substring($docDir.Length).TrimStart('\', '/')
|
||||
|
||||
$inCodeFence = $false
|
||||
for ($lineNumber = 0; $lineNumber -lt $lines.Count; $lineNumber++) {
|
||||
$line = $lines[$lineNumber]
|
||||
if ($line.TrimStart() -match '^(```|~~~)') {
|
||||
$inCodeFence = -not $inCodeFence
|
||||
continue
|
||||
}
|
||||
if ($inCodeFence) { continue }
|
||||
|
||||
$lineForParsing = [regex]::Replace($line, '`[^`]*`', '')
|
||||
|
||||
# Process markdown and HTML images
|
||||
$imagePatterns = @(
|
||||
@{ Pattern = "!\[([^\]]*)\]\(([^)]+)\)"; Type = "Markdown"; AltGroup = 1; UrlGroup = 2 }
|
||||
@{ Pattern = '<img\s+[^>]*>'; Type = "HTML"; AltGroup = -1; UrlGroup = -1 }
|
||||
)
|
||||
|
||||
foreach ($pattern in $imagePatterns) {
|
||||
foreach ($match in [regex]::Matches($lineForParsing, $pattern.Pattern)) {
|
||||
$altText = ""
|
||||
$url = ""
|
||||
|
||||
if ($pattern.Type -eq "Markdown") {
|
||||
$altText = $match.Groups[$pattern.AltGroup].Value
|
||||
$url = $match.Groups[$pattern.UrlGroup].Value
|
||||
} else {
|
||||
# Extract from HTML
|
||||
$imgTag = $match.Value
|
||||
if ($imgTag -match 'alt\s*=\s*[`"'']([^`"'']*)[`"'']') { $altText = $matches[1] }
|
||||
if ($imgTag -match 'src\s*=\s*[`"'']([^`"'']*)[`"'']') { $url = $matches[1] }
|
||||
}
|
||||
|
||||
if (-not $altText.Trim() -and $url) {
|
||||
$brokenReferences += Add-BrokenReference $relPath ($lineNumber + 1) $match.Value "[$($pattern.Type)] Missing alt text for image" "Image"
|
||||
} elseif ($url -and $altText) {
|
||||
# Validate URL format and file existence
|
||||
if ($url -match $expectedUrlPattern) {
|
||||
$relativePathInUrl = $matches[1]
|
||||
$fileNameFromUrl = [System.IO.Path]::GetFileNameWithoutExtension($relativePathInUrl)
|
||||
|
||||
if ($altText -ne $fileNameFromUrl) {
|
||||
$brokenReferences += Add-BrokenReference $relPath ($lineNumber + 1) $match.Value "[$($pattern.Type)] Alt text `"$altText`" ≠ filename `"$fileNameFromUrl`"" "Image"
|
||||
}
|
||||
|
||||
$expectedImagePath = Join-Path $PWD ($relativePathInUrl -replace "/", "\")
|
||||
if (-not (Test-Path $expectedImagePath)) {
|
||||
$brokenReferences += Add-BrokenReference $relPath ($lineNumber + 1) $match.Value "[$($pattern.Type)] Image not found at path: $relativePathInUrl" "Image"
|
||||
}
|
||||
} else {
|
||||
$urlIssues = @()
|
||||
if (-not $url.StartsWith('https://github.com/SoftFever/OrcaSlicer/blob/main/')) { $urlIssues += "URL must start with expected prefix" }
|
||||
if (-not $url.EndsWith('?raw=true')) { $urlIssues += "URL must end with '?raw=true'" }
|
||||
if ($url -match '^https?://(?!github\.com/SoftFever/OrcaSlicer)') { $urlIssues += "External URLs not allowed" }
|
||||
|
||||
$issueText = "[$($pattern.Type)] URL format issues: " + ($urlIssues -join '; ')
|
||||
$brokenReferences += Add-BrokenReference $relPath ($lineNumber + 1) $match.Value $issueText "Image"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Report results
|
||||
$linkErrors = $brokenReferences | Where-Object { $_.Type -eq "Link" }
|
||||
$imageErrors = $brokenReferences | Where-Object { $_.Type -eq "Image" }
|
||||
|
||||
if ($brokenReferences.Count -gt 0) {
|
||||
Write-Host "::error::Documentation validation failed"
|
||||
|
||||
# Build error summary for PR comment
|
||||
$errorSummary = ""
|
||||
|
||||
# Report link errors
|
||||
if ($linkErrors) {
|
||||
Write-Host "::group::🔗 Link Validation Errors"
|
||||
$errorSummary += "## 🔗 Link Validation Errors`n`n"
|
||||
$linkErrors | Group-Object SourceFile | ForEach-Object {
|
||||
Write-Host "📄 $($_.Name):" -ForegroundColor Yellow
|
||||
$errorSummary += "**📄 doc/$($_.Name):**`n"
|
||||
$_.Group | Sort-Object Line | ForEach-Object {
|
||||
Write-Host " Line $($_.Line): $($_.Target) - $($_.Issue)" -ForegroundColor Red
|
||||
Write-Host "::error file=doc/$($_.SourceFile),line=$($_.Line)::$($_.Target) - $($_.Issue)"
|
||||
$errorSummary += "- Line $($_.Line): ``$($_.Target)`` - $($_.Issue)`n"
|
||||
}
|
||||
$errorSummary += "`n"
|
||||
}
|
||||
Write-Host "::endgroup::"
|
||||
}
|
||||
|
||||
# Report image errors
|
||||
if ($imageErrors) {
|
||||
Write-Host "::group::🖼️ Image Validation Errors"
|
||||
$errorSummary += "## 🖼️ Image Validation Errors`n`n"
|
||||
$imageErrors | Group-Object SourceFile | ForEach-Object {
|
||||
Write-Host "📄 $($_.Name):" -ForegroundColor Yellow
|
||||
$errorSummary += "**📄 doc/$($_.Name):**`n"
|
||||
$_.Group | Sort-Object Line | ForEach-Object {
|
||||
Write-Host " Line $($_.Line): $($_.Issue)" -ForegroundColor Red
|
||||
Write-Host "::error file=doc/$($_.SourceFile),line=$($_.Line)::$($_.Issue)"
|
||||
$errorSummary += "- Line $($_.Line): $($_.Issue)`n"
|
||||
}
|
||||
$errorSummary += "`n"
|
||||
}
|
||||
Write-Host "::endgroup::"
|
||||
}
|
||||
|
||||
# Export error summary for PR comment
|
||||
Add-Content -Path $env:GITHUB_ENV -Value "VALIDATION_ERRORS<<EOF"
|
||||
Add-Content -Path $env:GITHUB_ENV -Value $errorSummary
|
||||
Add-Content -Path $env:GITHUB_ENV -Value "EOF"
|
||||
|
||||
exit 1
|
||||
} else {
|
||||
Write-Host "::notice::All documentation is valid!"
|
||||
exit 0
|
||||
}
|
||||
|
||||
- name: Comment on PR
|
||||
if: failure() && github.event_name == 'pull_request'
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const validationErrors = process.env.VALIDATION_ERRORS || '';
|
||||
|
||||
const body = `❌ **Documentation validation failed**
|
||||
|
||||
${validationErrors || 'Please check the workflow logs for details about the validation errors.'}`;
|
||||
|
||||
github.rest.issues.createComment({
|
||||
issue_number: context.issue.number,
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
body: body
|
||||
})
|
||||
Loading…
Add table
Add a link
Reference in a new issue