test-action-build-init.yml

name: test - action/build-init
on:
  push:
    branches: [main]
    paths:
      - .test/**
      - .github/workflows/test-action-build-init.yml
      - actions/ansible-docs-build-init/**
  pull_request:
    paths:
      - .test/**
      - .github/workflows/test-action-build-init.yml
      - actions/ansible-docs-build-init/**
  # Run once per week (Tuesday at 05:00 UTC)
  schedule:
    - cron: '0 5 * * 2'

jobs:
  tests:
    name: Init [ver=${{ matrix.antsibull-docs-version }}, skip=${{ matrix.skip-init }}, lenient=${{ matrix.lenient }}, fail-on-error=${{ matrix.fail-on-error }}, dest=${{ matrix.dest }}, collections=${{ matrix.collections }}, link-targets=${{ matrix.provide-link-targets != '' }}], intersphinx-links=${{ matrix.intersphinx-links }}, squash-hierarchy=${{ matrix.squash-hierarchy }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        skip-init: [false]
        collections:
          - ''
          - 'fake.collection'
          - 'first.collection second.collection'
        dest: ['']
        antsibull-docs-version:
          - ''  # there is no default so this will be ok
          - 1.0.0
          - main
        lenient:
          - true
          - false
        fail-on-error:
          - true
          - false
        provide-link-targets:
          - ''
          - |
            outside_reference_1
            outside_reference_2
        index-rst-source:
          - ''
        project:
          - ''
        copyright:
          - ''
        title:
          - ''
        html-short-title:
          - ''
        extra-conf:
          - ''
        extra-html-context:
          - ''
        extra-html-theme-options:
          - ''
        append-conf-py:
          - ''
        intersphinx-links: ['']
        squash-hierarchy:
          - false
        include:
          - skip-init: true
            dest: .test/simple-build
            lenient: false  # unused but needs a value
            fail-on-error: false  # unused but needs a value
            provide-link-targets: ''
            squash-hierarchy: false
          - skip-init: false
            dest: ''
            lenient: false
            fail-on-error: true
            intersphinx-links: |
              amazon_aws:https://ansible-collections.github.io/amazon.aws/branch/main/
              ansible_devel:https://docs.ansible.com/ansible-core/devel/
            squash-hierarchy: false
            index-rst-source: README.md
            title: Some long title
          - skip-init: false
            collections: foo.bar
            dest: ''
            lenient: false
            fail-on-error: true
            squash-hierarchy: true
            project: Foo
            copyright: Bar
            title: Long title
            html-short-title: Short title
            extra-conf: |
              foo=bar
              baz=bam
              long=This is "something long" 'with different quotes'
            extra-html-context: |
              foo=bam
              baz=bar
              long=Another "long" 'quotes' sentence
            extra-html-theme-options: |
              foo=baz
              long=Yet "another" long 'quotes' text
            append-conf-py: |
              # This is a special comment.
              # FOO BAR 1234

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - name: Install Python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
        with:
          python-version: 3.13

      # if we pass an empty string to dest-dir, it will override the default.
      # we can't copy the default into the matrix because it uses a templating
      # context (runner) that's unavailable in matrix.
      # We can't use two steps with opposing conditionals because we can't re-use
      # the id (and we need it in later steps).
      - name: Init
        id: init
        uses: $/actions/ansible-docs-build-init
        with:
          collections: ${{ matrix.collections }}
          # combining runner.temp and /docsbuild copies the default from the action
          # please keep in sync!
          dest-dir: ${{ matrix.dest || format('{0}/{1}', runner.temp, '/docsbuild') }}
          skip-init: ${{ matrix.skip-init }}
          antsibull-docs-version: ${{ matrix.antsibull-docs-version }}
          lenient: ${{ matrix.lenient }}
          provide-link-targets: ${{ matrix.provide-link-targets }}
          intersphinx-links: ${{ matrix.intersphinx-links }}
          squash-hierarchy: ${{ matrix.squash-hierarchy }}
          index-rst-source: ${{ matrix.index-rst-source }}
          project: ${{ matrix.project }}
          copyright: ${{ matrix.copyright }}
          title: ${{ matrix.title }}
          html-short-title: ${{ matrix.html-short-title }}
          extra-conf: ${{ matrix.extra-conf }}
          extra-html-context: ${{ matrix.extra-html-context }}
          extra-html-theme-options: ${{ matrix.extra-html-theme-options }}
          append-conf-py: ${{ matrix.append-conf-py }}

      - name: assert
        env:
          output_build_script: ${{ steps.init.outputs.build-script }}
          output_build_html: ${{ steps.init.outputs.build-html }}
        run: |
          set -x

          ORIGINAL_DIR=$(pwd)

          # check that the build script exists
          [ -f "$output_build_script" ] || exit 1

          # html dir is not guaranteed to exist but it is always at the same relative path
          # we'll use this to get to the "root" (dest-dir), even when we used a defaulted dir.
          mkdir -p "$output_build_html"
          cd "$output_build_html/../.."

          ${{ matrix.skip-init }} || (
            echo "::group::Show requirements.txt contents"
            cat requirements.txt
            echo
            echo "::endgroup::"

            echo "::group::Show build.sh contents"
            cat build.sh
            echo
            echo "::endgroup::"

            echo "::group::Show conf.py contents"
            cat conf.py
            echo
            echo "::endgroup::"
          )

          # by now, all requirements should have been installed, let's pip freeze
          pip freeze > "${{ runner.temp }}/pre-freeze.txt"

          # now we'll try to do a pip install again with the requirements file
          echo "::group::Install requirements again"
          pip install -r "requirements.txt" --disable-pip-version-check
          echo "::endgroup::"

          # and pip freeze again to compare
          pip freeze > "${{ runner.temp }}/post-freeze.txt"

          cmp "${{ runner.temp }}/pre-freeze.txt" "${{ runner.temp }}/post-freeze.txt" || exit 1

          # check if lenient mode was used
          # if lenient == 'true', the grep should fail and end up running the true command
          # if lenient == 'false', the grep should succeed and never run the false command
          # short circuit if skip-init is 'true'
          ${{ matrix.skip-init }} || grep -- '^nitpicky = True$' conf.py || ${{ matrix.lenient }} || exit 1

          # check if fail-on-error mode was used
          # if fail-on-error == 'true', the grep should fail (!succeed) and end up running the true command
          # if fail-on-error == 'false', the grep should succeed (!fail) and never run the false command
          # short circuit if skip-init is 'true'
          ${{ matrix.skip-init }} || ! grep -- '--fail-on-error' conf.py || ${{ matrix.fail-on-error }} || exit 1

          # check if provide-link-targets was used (being no empty)
          # :orphan: and the labels mentioned in provide-link-targets should end up in rst/_targets.rst
          # short circuit if skip-init is 'true' or matrix.provide-link-targets is empty
          ${{ matrix.skip-init }} || ${{ matrix.provide-link-targets == '' }} || grep -- '^:orphan:$' rst/_targets.rst || exit 1
          ${{ matrix.skip-init }} || ${{ matrix.provide-link-targets == '' }} || grep -- '^.. _outside_reference_1:$' rst/_targets.rst || exit 1
          ${{ matrix.skip-init }} || ${{ matrix.provide-link-targets == '' }} || grep -- '^.. _outside_reference_2:$' rst/_targets.rst || exit 1
          ${{ matrix.skip-init }} || ${{ matrix.provide-link-targets == '' }} || (pip install --upgrade rstcheck && rstcheck --report-level warning rst/_targets.rst) || exit 1

          # Check that intersphinx config was added to conf.py
          # These end up wrapped in python formatting, so stick to a naive test.
          ${{ matrix.skip-init }} || ${{ matrix.intersphinx-links == '' }} || grep -q -- 'ansible_devel' conf.py || exit 1
          ${{ matrix.skip-init }} || ${{ matrix.intersphinx-links == '' }} || grep -q -- 'https://docs.ansible.com/ansible-core/devel/' conf.py || exit 1
          ${{ matrix.skip-init }} || ${{ matrix.intersphinx-links == '' }} || grep -q -- 'amazon_aws' conf.py || exit 1
          ${{ matrix.skip-init }} || ${{ matrix.intersphinx-links == '' }} || grep -q -- 'https://ansible-collections.github.io/amazon.aws/branch/main/' conf.py || exit 1

          # Check that the squash hierarchy flag was added
          ${{ matrix.squash-hierarchy }} && (grep -q -- ' --squash-hierarchy ' build.sh || exit 1)

          # Check if provide-link-targets was not used when being empty
          # short circuit if skip-init is 'true' or matrix.provide-link-targets is not empty
          ${{ matrix.skip-init }} || ${{ matrix.provide-link-targets != '' }} || ! test -e rst/_targets.rst || exit 1

          # Check whether index-rst-source worked
          ${{ matrix.index-rst-source && 'true' || 'false' }} && (diff "${ORIGINAL_DIR}/${{ matrix.index-rst-source }}" rst/index.rst || exit 1)

          # Check whether config options worked
          ${{ matrix.project && 'true' || 'false' }} && (grep "project = '${{ matrix.project }}'" conf.py || exit 1)
          ${{ matrix.copyright && 'true' || 'false' }} && (grep "copyright = '${{ matrix.copyright }}'" conf.py || exit 1)
          ${{ matrix.title && 'true' || 'false' }} && (grep "title = '${{ matrix.title }}'" conf.py || exit 1)
          ${{ matrix.title && !matrix.html-short-title && 'true' || 'false' }} && (grep "html_short_title = '${{ matrix.title }}'" conf.py || exit 1)
          ${{ matrix.html-short-title && 'true' || 'false' }} && (grep "html_short_title = '${{ matrix.html-short-title }}'" conf.py || exit 1)

          # TODO Check extra-conf
          # TODO Check extra-html-context
          # TODO Check extra-html-theme-options

          ${{ matrix.append-conf-py && 'true' || 'false' }} && (grep -E '^# This is a special comment\.$' conf.py || exit 1)
          ${{ matrix.append-conf-py && 'true' || 'false' }} && (grep -E '^# FOO BAR 1234$' conf.py || exit 1)

          # This must be the last line
          exit 0