publish-docs.yml

name: Build Documentation

on:
  push:
    branches:
      - dev
      - main
      - new/doc-generation
  pull_request:
  release:
    types:
      - published

jobs:
  build:
    name: Build the documentation
    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: |
            let latest_release = github.rest.repos.getLatestRelease({
              owner: context.repo.owner,
              repo: context.repo.repo
            });
            
            if (context.payload.release && latest_release.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

      - run: echo

  publish:
    name: Publish the documentation
    runs-on: ubuntu-latest
    needs:
      - build
    # Make sure we avoid a race condition =)
    concurrency:
      group: "pages"
      cancel-in-progress: false
    permissions:
      contents: write
      pages: write
      id-token: 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: "static/docs"

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

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

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

      - name: Override the latest version if necessary
        if: ${{ github.event_name == 'release' }}
        run: |
          rm -f latest && ln -s ${{ github.ref_name }} latest

      - 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 "Rebuild ${{ github.ref_name }} from ${{ github.sha }}";
          git push origin static/docs;

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v5
        with:
          enablement: true

      - name: Push the rendered documentation site to GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: .

      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4