docs.yaml

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: "2.0.0rc2"
            source: "tags"
            python: "3.12"
            sphinx: "8.2.3"
            mermaid: "1.0.0"
            jinja: "3.1.1"
          - version: "1.11.7"
            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: "next"
            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@v6
        with:
          path: docs.octoprint.org
          persist-credentials: false

      - 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@v6
        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 }} six

      - 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@v6
        with:
          repository: "OctoPrint/OctoPrint"
          ref: ${{ matrix.version }}
          path: OctoPrint
          persist-credentials: false

      - 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@v6
        with: # this intentionally lacks a persist_credentials: false, as we need to push again!
          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