docs #2087
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: Build & publish docs | |
| on: | |
| push: | |
| branches: | |
| - master | |
| repository_dispatch: | |
| types: [docs] | |
| workflow_dispatch: | |
| jobs: | |
| build: | |
| name: Build docs | |
| runs-on: ubuntu-latest | |
| strategy: | |
| matrix: | |
| # you must not use anything but include here or the version.json generation will fail! | |
| include: | |
| - version: "1.11.3" | |
| source: "tags" | |
| python: "3.10" | |
| sphinx: "4.5.0" | |
| mermaid: "0.7.1" | |
| jinja: "3.1.1" | |
| - version: "1.10.3" | |
| source: "tags" | |
| python: "3.10" | |
| sphinx: "4.5.0" | |
| mermaid: "0.7.1" | |
| jinja: "3.1.1" | |
| - version: "main" | |
| source: "heads" | |
| python: "3.10" | |
| sphinx: "4.5.0" | |
| mermaid: "0.7.1" | |
| jinja: "3.1.1" | |
| - version: "dev" | |
| source: "heads" | |
| python: "3.12" | |
| sphinx: "8.2.3" | |
| mermaid: "1.0.0" | |
| jinja: "3.1.1" | |
| - version: "wip/alt-comm" | |
| slug: "alt-comm" | |
| source: "heads" | |
| python: "3.12" | |
| sphinx: "8.2.3" | |
| mermaid: "1.0.0" | |
| jinja: "3.1.1" | |
| steps: | |
| - name: 🧾 Log event & matrix, determine slug | |
| run: | | |
| echo "Event: ${{ github.event_name }} - ${{ toJson(github.event.client_payload) }}" | |
| echo "Matrix: ${{ matrix.version }}, ${{ matrix.slug }}, ${{ matrix.source }}, ${{ matrix.python }}, ${{ matrix.mermaid }}" | |
| echo "Formatted ref: ${{ format('refs/{0}/{1}', matrix.source, matrix.version) }}" | |
| DOC_SLUG="${{ matrix.slug || matrix.version }}" | |
| echo "DOC_SLUG=$DOC_SLUG" >> $GITHUB_ENV | |
| - name: 🛡️ Disable AppArmor | |
| uses: cisagov/action-disable-apparmor@437d94f26a2e4bf8c03acfb500a6afc688b497db # v1.0.0 | |
| - name: ⬇ Checkout docs.octoprint.org | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| uses: actions/checkout@v4 | |
| with: | |
| path: docs.octoprint.org | |
| - name: 👀 Determine latest OctoPrint release | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| run: | | |
| OCTOPRINT_VERSION=$(curl -i https://github.com/OctoPrint/OctoPrint/releases/latest | grep -i location: | head -n1 | awk -F/ '{print $NF}' | tr -d '\r') | |
| echo "OCTOPRINT_VERSION=$OCTOPRINT_VERSION" >> $GITHUB_ENV | |
| - name: 🐍 Set up Python ${{ matrix.python }} | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: ${{ matrix.python }} | |
| - name: 🐍 Preinstall some dependencies | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| run: | | |
| pip install sphinx==${{ matrix.sphinx }} sphinxcontrib-mermaid==${{ matrix.mermaid }} Jinja2==${{ matrix.jinja }} | |
| - name: 🏗 Set up NodeJS | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| uses: actions/setup-node@v3 | |
| with: | |
| node-version: "20" | |
| - name: 🏗 Prepare stuff for mermaid | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| run: | | |
| npx puppeteer browsers install chrome-headless-shell | |
| echo '{"args": ["--no-sandbox"]}' > puppeteer-config.json | |
| cat puppeteer-config.json | |
| npm install @mermaid-js/mermaid-cli | |
| - name: ⬇ Checkout OctoPrint | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: "OctoPrint/OctoPrint" | |
| ref: ${{ matrix.version }} | |
| path: OctoPrint | |
| - name: 🏗 Install OctoPrint | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| run: | | |
| cd ${{ github.workspace }}/OctoPrint | |
| pip install .[develop,docs] | |
| - name: 🔄 Generate versions.json | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| run: | | |
| python ${{ github.workspace }}/docs.octoprint.org/util/versions_from_matrix.py ${{ github.workspace }}/docs.octoprint.org/.github/workflows/docs.yaml versions.json | |
| - name: 🏗 Build docs | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| run: | | |
| cd ${{ github.workspace }}/docs.octoprint.org/util/versionselector | |
| python versionselector.py ${{ github.workspace }}/OctoPrint/docs/ ${{ env.DOC_SLUG }} ${{ env.OCTOPRINT_VERSION }} ${{ github.workspace }}/versions.json -D mermaid_cmd=${{ github.workspace }}/node_modules/.bin/mmdc -D mermaid_params="-p${{ github.workspace }}/puppeteer-config.json" -D mermaid_output_format=svg -D mermaid_version= | |
| echo ".rst-content object[type^='image/']{width: 100%;}" >> ${{ github.workspace }}/OctoPrint/docs/_build/html/${{ env.DOC_SLUG }}/_static/theme_overrides.css | |
| #- name: 🔎 Run link check | |
| # id: lc | |
| # uses: peter-evans/link-checker@v1 | |
| # with: | |
| # args: -v -r -d ./OctoPrint/docs/_build/html/${{ env.DOC_SLUG }} ./OctoPrint/docs/_build/html/${{ env.DOC_SLUG }} | |
| #- name: 🔎 Evaluate link check | |
| # run: exit ${{ steps.lc.outputs.exit_code }} | |
| - name: ⬆ Persist build result | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event.client_payload.ref == format('refs/{0}/{1}', matrix.source, matrix.version) | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: ${{ env.DOC_SLUG }} | |
| path: ${{ github.workspace }}/OctoPrint/docs/_build/html/${{ env.DOC_SLUG }} | |
| deploy: | |
| name: Deploy docs | |
| needs: build | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: ⬇ Checkout docs.octoprint.org | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: gh-pages | |
| path: docs | |
| - name: ⬇ Fetch all artifacts | |
| uses: actions/download-artifact@v4 | |
| with: | |
| path: artifacts | |
| - name: 🧹 Cleanup all docs | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' | |
| run: | | |
| count=`ls -1 artifacts | wc -l` | |
| if [ $count != '0' ]; then | |
| rm -rf docs/* || true | |
| touch docs/.nojekyll | |
| cp -rv artifacts/* docs | |
| fi | |
| - name: 🧹 Cleanup regenerated docs | |
| if: github.event_name == 'repository_dispatch' | |
| run: | | |
| # there should only be one artifact | |
| count=`ls -1 artifacts | wc -l` | |
| if [ $count == '1' ]; then | |
| version=$(ls artifacts | head -n1) | |
| echo "Version is $version" | |
| rm -rf "docs/$version" || true | |
| cp -r "artifacts/$version" docs/ | |
| fi | |
| - name: 🚧 Generate versions.json | |
| run: | | |
| cd docs | |
| echo "[]" > versions.json | |
| for version in *; do | |
| if [ -d "$version" ]; then | |
| aliases="[]" | |
| if [ "$version" == "main" ]; then | |
| aliases="[\"latest\"]" | |
| fi | |
| echo "Adding $version at /en/$version..." | |
| versions=$(jq --arg version "${version}" --argjson aliases "${aliases}" '. + [{"version": "/en/\( $version )", "title": $version, "aliases": $aliases}]' versions.json) | |
| echo -n $versions > versions.json | |
| else | |
| echo "$version is not a directory, ignoring" | |
| fi | |
| done | |
| echo "Versions:" | |
| cat versions.json | |
| - name: 🚀 Commit & deploy | |
| uses: EndBug/add-and-commit@v9 | |
| with: | |
| cwd: "docs" | |
| message: "Publish new build of docs" | |
| default_author: github_actions |