auto-update-documentation.yml

name: Autoupdate Documentation
#
#  Takes care of updating the Vespa documentation.
#

on:
  workflow_dispatch: # Allow manual triggering of the workflow

  schedule:
    - cron: "0 0 * * *"

permissions:
  contents: write
  pull-requests: write

defaults:
  run:
    # This ensures that options "pipefail" and "errexit" are set for all steps.
    # Ref: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#defaultsrunshell
    shell: bash

# Limit concurrency to better handle commit and push operations.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}

jobs:
  update-vespa-version:
    #
    # This job updates the Vespa version in the documentation.
    #
    runs-on: ubuntu-24.04

    steps:
      - uses: actions/checkout@v4

      - name: Setup Dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y xq

      - name: Update Vespa version
        id: update-docs
        run: |
          VESPA_VERSION=$(curl -sSL https://repo1.maven.org/maven2/com/yahoo/vespa/parent/maven-metadata.xml | \
           xq -x '/metadata/versioning/latest')

          echo "Vespa version: $VESPA_VERSION"
          echo "version=$VESPA_VERSION" >> $GITHUB_OUTPUT

          # Update the Vespa version in the documentation configuration file.
          sed -i'' "s/\(vespa_version:\) \"[0-9\.]*\"/\1 \"${VESPA_VERSION}\"/" _config.yml

          git diff
          echo "has-changes=$(git status --short | wc -l)" >> $GITHUB_OUTPUT

      - name: Commit changes
        if: ${{ steps.update-docs.outputs.has-changes != '0' }}
        uses: ./.github/actions/commit-updated-docs
        with:
          commit-message: "Update Vespa version to ${{ steps.update-docs.outputs.version }}."
          files: _config.yml
          push: ${{ contains(fromJSON('["workflow_dispatch", "schedule"]'), github.event_name) && github.ref_name == 'master' }}

  update-vespa-cli-doc:
    #
    # This job updates the Vespa CLI documentation.
    #
    runs-on: ubuntu-latest

    # Make sure each job runs after the previous one, regardless of the outcome.
    # This trick is useful to prevent two jobs from running concurrently and trying to
    #  push changes to the repository at the same time.
    if: ${{ success() || failure() }}
    needs:
      - update-vespa-version

    env:
      VESPA_CLI_DOC_DIR: en/reference/vespa-cli

    steps:
      - uses: actions/checkout@v4

      - name: Install Vespa CLI
        uses: vespa-engine/setup-vespa-cli-action@v1

      - name: Generate Vespa CLI Documentation
        id: update-docs
        working-directory: ${{ env.VESPA_CLI_DOC_DIR }}
        run: |
          vespa gendoc .

          for f in $(git status --short . | awk '{print $2}'); do
            title=${f//.md/}
            title=${title//.\//}
            title=${title//_/ }
            (echo -e "---\ntitle: $title\nrender_with_liquid: false\n---\n"; cat ${f}) > ${f}.new
            mv ${f}.new ${f};
          done

          # ensure links are to .html
          sed -i'' 's/\(vespa.*\).md)/\1.html)/' *.md
          # create links
          sed -i'' 's#\(https://[a-z.]*vespa.ai/[^[:space:]]*\)#[\1](\1)#g' *.md

          git diff
          echo "has-changes=$(git status --short | wc -l)" >> $GITHUB_OUTPUT

      - name: Commit changes
        if: ${{ steps.update-docs.outputs.has-changes != '0' }}
        uses: ./.github/actions/commit-updated-docs
        with:
          commit-message: "Update 'Vespa-CLI' reference documentation."
          files: ${{ env.VESPA_CLI_DOC_DIR }}
          push: ${{ contains(fromJSON('["workflow_dispatch", "schedule"]'), github.event_name) && github.ref_name == 'master' }}

  update-metric-reference:
    #
    # This job updates the Vespa metric reference documentation.
    # Ref https://github.com/vespa-engine/vespa/blob/master/metrics/src/main/java/ai/vespa/metrics/docs/MetricDocumentation.java
    #
    runs-on: ubuntu-24.04 # Use Ubuntu 24.04 for the xq dependency

    # Make sure each job runs after the previous one, regardless of the outcome.
    # This trick is useful to prevent two jobs from running concurrently and trying to
    #  push changes to the repository at the same time.
    if: ${{ success() || failure() }}
    needs:
      - update-vespa-cli-doc

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: "temurin"
          java-version: "17"

      - name: Setup xq
        run: |
          sudo apt-get install -y xq

      - name: Get Latest Vespa version
        id: vespa-metadata
        run: |
          VESPA_VERSION=$(curl -sSL https://repo1.maven.org/maven2/com/yahoo/vespa/parent/maven-metadata.xml | \
           xq -x '/metadata/versioning/latest')
          echo "Using version: ${VESPA_VERSION}"
          echo "version=$VESPA_VERSION" >> "${GITHUB_OUTPUT}"

      - name: Update Metric Reference
        id: update-docs
        env:
          VESPA_VERSION: ${{ steps.vespa-metadata.outputs.version }}
        run: |
          curl -SsLo metrics.jar "https://repo1.maven.org/maven2/com/yahoo/vespa/metrics/${VESPA_VERSION}/metrics-${VESPA_VERSION}.jar"
          java -cp metrics.jar ai.vespa.metrics.docs.DocumentationGenerator en/reference
          rm metrics.jar
          
          git diff -- en/reference
          echo "has-changes=$(git status --short -- en/reference | wc -l)" >> "${GITHUB_OUTPUT}"

      - name: Commit changes
        if: ${{ steps.update-docs.outputs.has-changes != '0' }}
        uses: ./.github/actions/commit-updated-docs
        with:
          commit-message: "Update 'Metric' reference documentation."
          files: "en/reference/*-metrics-reference.html"
          push: ${{ contains(fromJSON('["workflow_dispatch", "schedule"]'), github.event_name) && github.ref_name == 'master' }}