Documentation #314
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # file: .github/workflows/documentation.yml | |
| # version: 1.1.2 | |
| # guid: docs-automation-workflow-2025 | |
| name: Documentation | |
| on: | |
| push: | |
| branches: [main] | |
| paths: | |
| - 'docs/**' | |
| - '**/*.md' | |
| - '.github/workflows/documentation.yml' | |
| pull_request: | |
| paths: | |
| - 'docs/**' | |
| - '**/*.md' | |
| - '.github/workflows/documentation.yml' | |
| schedule: | |
| - cron: '0 5 * * 1' | |
| workflow_dispatch: | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| build-docs: | |
| name: Build Documentation | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| with: | |
| submodules: recursive | |
| - name: Generate helper documentation | |
| uses: falkcorp/gha-docs-generator@ecaefb4b0110d11683bc7ad0b6b968209aeca4af # v1.1.6-rc.4 | |
| with: | |
| source-dir: .github/workflows/scripts | |
| workflows-dir: .github/workflows | |
| output-dir: docs/generated | |
| - name: Detect documentation toolchain | |
| id: detect | |
| shell: bash | |
| run: | | |
| set -euo pipefail | |
| tool="none" | |
| if [ -f "mkdocs.yml" ] || [ -f "mkdocs.yaml" ]; then | |
| tool="mkdocs" | |
| elif [ -f "docs/conf.py" ]; then | |
| tool="sphinx" | |
| elif [ -f "package.json" ] && jq -e '.scripts.buildDocs' package.json >/dev/null 2>&1; then | |
| tool="npm" | |
| fi | |
| echo "tool=${tool}" >> "$GITHUB_OUTPUT" | |
| echo "Detected documentation tool: ${tool}" | |
| - name: Build with MkDocs | |
| if: steps.detect.outputs.tool == 'mkdocs' | |
| run: | | |
| pip install --upgrade pip | |
| pip install mkdocs mkdocs-material | |
| mkdocs build --strict --site-dir site | |
| - name: Build with Sphinx | |
| if: steps.detect.outputs.tool == 'sphinx' | |
| run: | | |
| python -m pip install --upgrade pip | |
| python -m pip install sphinx sphinx-autobuild sphinx-rtd-theme | |
| sphinx-build -b html docs/ _build/html | |
| - name: Build with npm script | |
| if: steps.detect.outputs.tool == 'npm' | |
| run: | | |
| npm ci || npm install | |
| npm run buildDocs | |
| - name: Validate Markdown links | |
| run: | | |
| pip install --upgrade pip | |
| pip install linkchecker | |
| if find . -name "*.md" | head -1 | grep -q .; then | |
| linkchecker --ignore-url "mailto:" --ignore-url "http://localhost" docs || true | |
| else | |
| echo "No Markdown files detected in docs/." | |
| fi | |
| - name: Upload documentation artifact | |
| id: upload | |
| if: steps.detect.outputs.tool != 'none' | |
| uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 | |
| with: | |
| name: documentation-build | |
| path: | | |
| site | |
| _build/html | |
| if-no-files-found: ignore | |
| deploy-docs: | |
| name: Deploy Documentation | |
| needs: build-docs | |
| if: needs.build-docs.result == 'success' && github.ref == 'refs/heads/main' | |
| runs-on: ubuntu-latest | |
| environment: documentation | |
| env: | |
| DOCS_DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| steps: | |
| - name: Check deployment token | |
| if: env.DOCS_DEPLOY_TOKEN == '' | |
| run: | | |
| echo "DOCS_DEPLOY_TOKEN secret not set; skipping deployment." | |
| exit 0 | |
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| with: | |
| submodules: recursive | |
| if: env.DOCS_DEPLOY_TOKEN != '' | |
| - name: Download documentation artifact | |
| uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 | |
| if: env.DOCS_DEPLOY_TOKEN != '' | |
| continue-on-error: true | |
| with: | |
| name: documentation-build | |
| path: docs-build | |
| - name: Deploy to GitHub Pages | |
| uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0 | |
| if: env.DOCS_DEPLOY_TOKEN != '' && hashFiles('docs-build/**') != '' | |
| with: | |
| github_token: ${{ env.DOCS_DEPLOY_TOKEN }} | |
| publish_dir: docs-build/site | |
| keep_files: true |