.github/workflows/documentation.yml

name: Build Documentation

on:
  push:
    tags-ignore:
      - "v*"
  pull_request:
  release:
    types:
      - published

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          submodules: "recursive"

      - name: Update system packages
        run: sudo apt-get update -y

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.x"

      - name: Install Python dependencies and update cert
        run: |
          pip install wheel boto3 && \
          pip install certifi -U && \
          pip install .[obj,dev]

      - name: Resolve the target CLI version
        uses: actions/github-script@v7
        id: resolve-cli-version
        with:
          script: |
            const latest_release = await github.rest.repos.getLatestRelease({
              owner: context.repo.owner,
              repo: context.repo.repo
            });
            
            if (context.payload.release && latest_release.data.id == context.payload.release.id) {
              let result = context.payload.release.tag_name;
            
              if (result.startsWith('v')) {
                result = result.slice(1);
              }
            
              return result;
            }
            
            return '0.0.0.dev+' + context.sha.substring(0, 7);
          result-encoding: string

      - name: Build the documentation
        run: make create-version && make generate-docs
        env:
          # We need to define a token to prevent the CLI from
          # attempting to do a first-time configuration.
          LINODE_CLI_TOKEN: foobar
          LINODE_CLI_VERSION: ${{ steps.resolve-cli-version.outputs.result }}

      - name: Upload the artifact
        uses: actions/upload-artifact@v4
        with:
          name: generated-docs-html
          path: docs/build/html

  pages-commit:
    name: Commit to Pages Branch
    runs-on: ubuntu-latest
    needs:
      - build
    # Make sure we avoid a race condition =)
    concurrency:
      group: "docs-stage"
      cancel-in-progress: false
    permissions:
      contents: write

    if: (github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'dev' || github.ref_name == 'new/doc-generation' )) || (github.ref_type == 'tag')
    steps:
      - name: Checkout the documentation branch
        continue-on-error: true
        id: checkout-docs
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          submodules: "recursive"
          ref: "_documentation"

      - name: Create the documentation branch if it does not already exist
        if: "${{ steps.checkout-docs.outcome != 'success' }}"
        run: git switch --orphan _documentation

      - name: Ensure any previous documentation for this branch is removed
        run: rm -rf "./${{ github.ref_name }}"

      - name: Download the artifact from the build job
        uses: actions/download-artifact@v4
        with:
          name: generated-docs-html
          path: "${{ github.ref_name }}"

      - name: Override the latest version if necessary
        if: ${{ github.ref_type == 'tag' }}
        run: |
          rm -rf latest && cp -r ${{ github.ref_name }} latest

      - name: Overlay static files
        run: |
          echo "<head><meta http-equiv='refresh' content='0; URL=latest/index.html'></head>" > index.html;
          touch .nojekyll

      - name: Commit and push this change
        run: |
          git config user.name "Documentation Publisher";
          git config user.email "dl-linode-dev-dx@akamai.com";
          git add .;
          git commit --allow-empty -m "Build ${{ github.ref_name }} from ${{ github.sha }}";
          git push origin _documentation;

  upload-release-asset:
    name: Upload Release Asset
    runs-on: ubuntu-latest
    needs:
      - build
    if: github.ref_type == 'tag'
    steps:
      - name: Download the artifact from the previous job
        uses: actions/download-artifact@v4
        with:
          name: generated-docs-html
          path: ".build/${{ github.ref_name }}"

      - name: Archive the built documentation
        run: |
          cd .build/${{ github.ref_name }} && tar -czvf ../documentation.tar.gz *

      - name: Upload the documentation as a release asset
        uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191
        with:
          files: .build/documentation.tar.gz
          tag_name: ${{ github.ref_name }}