Convert EnergyPlus Docs #16
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
| name: Convert EnergyPlus Docs | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| versions: | |
| description: 'Comma-separated version tags to convert (e.g., "v25.2.0,v25.1.0") or "all"' | |
| required: true | |
| default: "all" | |
| force_rebuild: | |
| description: "Force rebuild even if cached" | |
| required: false | |
| type: boolean | |
| default: false | |
| workflow_call: | |
| inputs: | |
| versions: | |
| description: 'Comma-separated version tags to convert or "all"' | |
| required: true | |
| type: string | |
| force_rebuild: | |
| required: false | |
| type: boolean | |
| default: false | |
| permissions: | |
| contents: write | |
| pages: write | |
| jobs: | |
| # Generate the matrix of versions to build | |
| prepare: | |
| runs-on: ubuntu-latest | |
| outputs: | |
| matrix: ${{ steps.set-matrix.outputs.matrix }} | |
| all_versions: ${{ steps.set-matrix.outputs.all_versions }} | |
| steps: | |
| - name: Check out | |
| uses: actions/checkout@v4 | |
| - name: Set up the environment | |
| uses: ./.github/actions/setup-python-env | |
| - name: Set up Node.js | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: "20" | |
| cache: "npm" | |
| cache-dependency-path: idf-editor/package-lock.json | |
| - name: Build IDF editor bundle | |
| run: cd idf-editor && npm ci --silent && npm run build | |
| - name: Upload IDF editor bundle | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: idf-editor-bundle | |
| path: | | |
| idf-editor/dist/idf-editor.js | |
| idf-editor/dist/idf-editor.css | |
| retention-days: 1 | |
| - name: Determine versions to build | |
| id: set-matrix | |
| run: | | |
| if [ "${{ inputs.versions }}" = "all" ]; then | |
| VERSIONS=$(uv run python -c "from scripts.config import TARGET_VERSIONS; print(','.join(TARGET_VERSIONS))") | |
| else | |
| VERSIONS="${{ inputs.versions }}" | |
| fi | |
| # Convert comma-separated to JSON array | |
| JSON_ARRAY=$(echo "$VERSIONS" | tr ',' '\n' | jq -R . | jq -sc 'map(select(length > 0))') | |
| echo "matrix={\"version\":${JSON_ARRAY}}" >> "$GITHUB_OUTPUT" | |
| echo "all_versions=${VERSIONS}" >> "$GITHUB_OUTPUT" | |
| # Build each version as a parallel matrix job | |
| convert: | |
| needs: prepare | |
| runs-on: ubuntu-latest | |
| strategy: | |
| matrix: ${{ fromJson(needs.prepare.outputs.matrix) }} | |
| fail-fast: false | |
| steps: | |
| - name: Check out | |
| uses: actions/checkout@v4 | |
| - name: Set up the environment | |
| uses: ./.github/actions/setup-python-env | |
| - name: Install Pandoc | |
| uses: pandoc/actions/setup@v1 | |
| - name: Download IDF editor bundle | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: idf-editor-bundle | |
| path: idf-editor/dist/ | |
| - name: Copy IDF editor bundle to assets | |
| run: cp idf-editor/dist/idf-editor.js idf-editor/dist/idf-editor.css scripts/assets/ | |
| - name: Compute short version | |
| id: short | |
| run: | | |
| SHORT=$(uv run python -c "from scripts.config import version_to_short; print(version_to_short('${{ matrix.version }}'))") | |
| echo "version_short=${SHORT}" >> "$GITHUB_OUTPUT" | |
| - name: Compute cache key | |
| id: cache-key | |
| run: | | |
| SCRIPTS_HASH=$(find scripts/ idf-editor/src/ -type f \( -name '*.py' -o -name '*.lua' -o -name '*.ts' -o -name '*.css' \) | sort | xargs sha256sum | sha256sum | cut -d' ' -f1) | |
| echo "key=docs-${{ matrix.version }}-${SCRIPTS_HASH}" >> "$GITHUB_OUTPUT" | |
| - name: Cache built version | |
| id: cache | |
| if: ${{ !inputs.force_rebuild }} | |
| uses: actions/cache@v4 | |
| with: | |
| path: build/${{ steps.short.outputs.version_short }} | |
| key: ${{ steps.cache-key.outputs.key }} | |
| - name: Clone EnergyPlus source (sparse, doc/ only) | |
| if: steps.cache.outputs.cache-hit != 'true' | |
| run: | | |
| git clone --filter=blob:none --no-checkout --depth=1 \ | |
| --branch ${{ matrix.version }} --single-branch \ | |
| https://github.com/NatLabRockies/EnergyPlus.git \ | |
| build/sources/${{ matrix.version }} | |
| git -C build/sources/${{ matrix.version }} sparse-checkout set doc | |
| git -C build/sources/${{ matrix.version }} checkout | |
| - name: Convert docs | |
| if: steps.cache.outputs.cache-hit != 'true' | |
| run: | | |
| uv run python -m scripts.convert \ | |
| --source build/sources/${{ matrix.version }} \ | |
| --output build/${{ steps.short.outputs.version_short }} \ | |
| --version ${{ matrix.version }} \ | |
| --verbose | |
| - name: Upload build artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: docs-${{ steps.short.outputs.version_short }} | |
| path: build/${{ steps.short.outputs.version_short }}/site/ | |
| retention-days: 1 | |
| # Merge all version outputs and deploy | |
| deploy: | |
| needs: [prepare, convert] | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Check out | |
| uses: actions/checkout@v4 | |
| - name: Set up the environment | |
| uses: ./.github/actions/setup-python-env | |
| - name: Download all version artifacts | |
| uses: actions/download-artifact@v4 | |
| with: | |
| path: dist-artifacts/ | |
| - name: Restore existing gh-pages content | |
| if: ${{ inputs.versions != 'all' }} | |
| run: | | |
| git fetch origin gh-pages:gh-pages 2>/dev/null || true | |
| if git rev-parse --verify gh-pages >/dev/null 2>&1; then | |
| git worktree add gh-pages-checkout gh-pages | |
| # Copy existing version directories (v*/) to dist/ | |
| mkdir -p dist | |
| for dir in gh-pages-checkout/v*/; do | |
| [ -d "$dir" ] && cp -a "$dir" dist/ | |
| done | |
| git worktree remove gh-pages-checkout --force | |
| fi | |
| - name: Merge version outputs | |
| run: | | |
| mkdir -p dist | |
| # Move each version artifact to its versioned directory (overwrites restored versions) | |
| for dir in dist-artifacts/docs-*/; do | |
| version_short=$(basename "$dir" | sed 's/^docs-//') | |
| # Remove old version if restored from gh-pages | |
| rm -rf "dist/${version_short}" | |
| mv "$dir" "dist/${version_short}" | |
| done | |
| # Discover all versions now in dist/ and regenerate root files | |
| uv run python -c " | |
| from scripts.version_manager import _discover_versions, generate_versions_json, generate_root_landing, generate_robots_txt, generate_sitemap | |
| from pathlib import Path | |
| dist = Path('dist') | |
| versions = _discover_versions(dist) | |
| generate_versions_json(versions, dist) | |
| generate_root_landing(dist, versions) | |
| generate_robots_txt(dist) | |
| generate_sitemap(dist, versions) | |
| " | |
| - name: Deploy to GitHub Pages | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./dist | |
| force_orphan: true | |
| cname: docs.idfkit.com |