diff --git a/.github/workflows/_shared-docs-build-pr.yml b/.github/workflows/_shared-docs-build-pr.yml index de0b3fd..2b43ee6 100644 --- a/.github/workflows/_shared-docs-build-pr.yml +++ b/.github/workflows/_shared-docs-build-pr.yml @@ -100,6 +100,10 @@ on: description: A space separated list of additional collections to install prior to building the documentation. required: false type: string + provide-link-targets: + description: A newline separated list of link targets that should not cause reference errors. A small RST file will be created during the build which contains these labels. + required: false + type: string outputs: artifact-name: @@ -225,6 +229,7 @@ jobs: antsibull-docs-version: '${{ inputs.init-antsibull-docs-version }}' lenient: ${{ inputs.init-lenient }} fail-on-error: ${{ inputs.init-fail-on-error }} + provide-link-targets: ${{ inputs.provide-link-targets }} - name: Build BASE id: build-base @@ -257,6 +262,7 @@ jobs: antsibull-docs-version: '${{ inputs.init-antsibull-docs-version }}' lenient: ${{ inputs.init-lenient }} fail-on-error: ${{ inputs.init-fail-on-error }} + provide-link-targets: ${{ inputs.provide-link-targets }} - name: Build HEAD id: build-head diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml index f22f75f..8910bcc 100644 --- a/.github/workflows/test-action-build-init.yml +++ b/.github/workflows/test-action-build-init.yml @@ -14,7 +14,7 @@ on: 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 }}] + 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 != '' }}] runs-on: ubuntu-latest strategy: fail-fast: false @@ -35,11 +35,17 @@ jobs: fail-on-error: - true - false + provide-link-targets: + - '' + - | + outside_reference_1 + outside_reference_2 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: '' steps: - name: Checkout @@ -66,6 +72,7 @@ jobs: skip-init: ${{ matrix.skip-init }} antsibull-docs-version: ${{ matrix.antsibull-docs-version }} lenient: ${{ matrix.lenient }} + provide-link-targets: ${{ matrix.provide-link-targets }} - name: assert env: @@ -102,3 +109,14 @@ jobs: # 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 + + # 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 diff --git a/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml index bbbfb7f..245e32b 100644 --- a/actions/ansible-docs-build-init/action.yml +++ b/actions/ansible-docs-build-init/action.yml @@ -36,6 +36,10 @@ inputs: The version of antsibull-docs to install. When set, it refers to a git ref from which to install. If not set, the latest version from PyPI is installed. required: false + provide-link-targets: + description: A newline separated list of link targets that should not cause reference errors. A small RST file will be created during the build which contains these labels. + required: false + type: string outputs: build-script: description: The path of the build script to execute. @@ -51,6 +55,7 @@ runs: id: init env: PIP_DISABLE_PIP_VERSION_CHECK: '1' + _INPUT_PROVIDE_LINK_TARGETS: ${{ inputs.provide-link-targets }} shell: bash run: | echo "::group::Installing antsibull-docs" @@ -72,6 +77,17 @@ runs: echo "::endgroup::" fi + if [[ "${_INPUT_PROVIDE_LINK_TARGETS}" != "" ]]; then + echo "::group::Create small RST file for link" + mkdir -p "${{ inputs.dest-dir }}/rst" + echo ":orphan:" > "${{ inputs.dest-dir }}/rst/_targets.rst" + while read -r line; do + echo ".. _${line}:" >> "${{ inputs.dest-dir }}/rst/_targets.rst" + done <<< "${_INPUT_PROVIDE_LINK_TARGETS}" + echo "This file just exists to provide link targets. Please ignore it." >> "${{ inputs.dest-dir }}/rst/_targets.rst" + echo "::endgroup::" + fi + echo "::group::Install additional requirements" pip install -r "${{ inputs.dest-dir }}/requirements.txt" echo "::endgroup::"