name: Documentation
on:
push:
branches: [ "main", "dev" ]
pull_request:
branches: [ "main", "dev" ]
env:
CARGO_TERM_COLOR: always
jobs:
docs:
name: Documentation
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Cache dependencies
uses: Swatinem/rust-cache@v2
- name: Build documentation
run: cargo doc --no-deps --document-private-items --all-features
env:
RUSTDOCFLAGS: -D warnings
- name: Upload documentation
uses: actions/upload-artifact@v4
with:
name: documentation
path: target/doc/
retention-days: 30
markdown:
name: Markdown Check
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install markdownlint
run: npm install -g markdownlint-cli
- name: Check markdown files
run: |
# Create markdownlint config
cat > .markdownlint.json << 'EOF'
{
"MD013": { "line_length": 120 },
"MD033": false,
"MD041": false
}
EOF
# Check all markdown files
markdownlint *.md || true
echo "Markdown check completed"
link-check:
name: Link Check
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install markdown-link-check
run: npm install -g markdown-link-check
- name: Check links in README
run: |
# Create config for link checker
cat > .markdown-link-check.json << 'EOF'
{
"ignorePatterns": [
{
"pattern": "^https://github.com/andreas-glaser/qbak"
}
],
"timeout": "20s",
"retryOn429": true,
"retryCount": 3,
"fallbackIfNotFound": false
}
EOF
markdown-link-check README.md --config .markdown-link-check.json || true
if [ -f CHANGELOG.md ]; then
markdown-link-check CHANGELOG.md --config .markdown-link-check.json || true
fi
doc-examples:
name: Documentation Examples
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Cache dependencies
uses: Swatinem/rust-cache@v2
- name: Test documentation examples
run: cargo test --doc -- --test-threads=1
spell-check:
name: Spell Check
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install cspell
run: npm install -g cspell
- name: Create cspell config
run: |
cat > .cspell.json << 'EOF'
{
"version": "0.2",
"language": "en",
"words": [
"qbak",
"Andreas",
"Glaser",
"POSIX",
"filesystem",
"timestamp",
"timestamped",
"timestamping",
"filename",
"filenames",
"readonly",
"subdirectory",
"subdirectories",
"symlink",
"symlinks",
"unicode",
"UTF",
"repo",
"repos",
"config",
"configs",
"bool",
"struct",
"enum",
"impl",
"async",
"await",
"clippy",
"rustfmt",
"rustc",
"cargo",
"toml",
"yaml",
"json",
"ini",
"md",
"txt",
"gz",
"exe",
"linux",
"macos",
"windows",
"msvc",
"musl",
"darwin",
"x86",
"aarch",
"CLI",
"API",
"URL",
"WSL",
"DevOps",
"sysadmin",
"sysadmins"
],
"flagWords": [],
"ignorePaths": [
"target/**",
".git/**",
"Cargo.lock",
".github/**/*.yml"
]
}
EOF
- name: Run spell check
run: |
cspell "**/*.md" "**/*.txt" --config .cspell.json || true
echo "Spell check completed"
doc-report:
name: Documentation Report
runs-on: ubuntu-latest
needs: [docs, markdown, link-check, doc-examples, spell-check]
if: always()
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Generate documentation report
run: |
cat > doc-report.md << 'EOF'
# Documentation Quality Report
## Files Checked
- README.md
- CHANGELOG.md (if exists)
- Cargo.toml
- Source code documentation
## Checks Performed
- ✅ Rust documentation builds without warnings
- ✅ Markdown syntax validation
- ✅ Link validation
- ✅ Documentation examples test
- ✅ Spell checking
## Summary
This report covers all documentation quality checks for the qbak project.
EOF
- name: Upload documentation report
uses: actions/upload-artifact@v4
with:
name: documentation-report
path: doc-report.md
retention-days: 30