From 0c97e3999ae3be3ec680edb2bf513aca5d54fedf Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 28 Apr 2022 13:13:52 +0200 Subject: [PATCH 1/8] Allow to provide extra labels. --- .github/workflows/_shared-docs-build-pr.yml | 6 ++++++ actions/ansible-docs-build-init/action.yml | 15 +++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/.github/workflows/_shared-docs-build-pr.yml b/.github/workflows/_shared-docs-build-pr.yml index de0b3fd..d3fe68f 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 comma 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/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml index bbbfb7f..c673795 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 comma 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. @@ -72,6 +76,17 @@ runs: echo "::endgroup::" fi + if [[ "${{ inputs.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 <<< "$(tr ',' '\n' <<< "${{ inputs.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::" From f4995c30f964f60f3ecdb447b263f832f790e511 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 18 Jun 2022 13:53:29 +0200 Subject: [PATCH 2/8] Change to use newlines instead of commas to separate entries. --- .github/workflows/_shared-docs-build-pr.yml | 2 +- actions/ansible-docs-build-init/action.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/_shared-docs-build-pr.yml b/.github/workflows/_shared-docs-build-pr.yml index d3fe68f..2b43ee6 100644 --- a/.github/workflows/_shared-docs-build-pr.yml +++ b/.github/workflows/_shared-docs-build-pr.yml @@ -101,7 +101,7 @@ on: required: false type: string provide-link-targets: - description: A comma 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. + 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 diff --git a/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml index c673795..cd8c80d 100644 --- a/actions/ansible-docs-build-init/action.yml +++ b/actions/ansible-docs-build-init/action.yml @@ -37,7 +37,7 @@ inputs: If not set, the latest version from PyPI is installed. required: false provide-link-targets: - description: A comma 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. + 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: @@ -82,7 +82,7 @@ runs: echo ":orphan:" > "${{ inputs.dest-dir }}/rst/_targets.rst" while read -r line; do echo ".. _${line}:" >> "${{ inputs.dest-dir }}/rst/_targets.rst" - done <<< "$(tr ',' '\n' <<< "${{ inputs.provide-link-targets }}")" + done <<< "${{ inputs.provide-link-targets }}" echo "This file just exists to provide link targets. Please ignore it." >> "${{ inputs.dest-dir }}/rst/_targets.rst" echo "::endgroup::" fi From 13b1c0558072f943448b5eb5b7dac10fb083e475 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 18 Jun 2022 19:55:16 +0200 Subject: [PATCH 3/8] Use input.provide-link-targets safely. --- actions/ansible-docs-build-init/action.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml index cd8c80d..245e32b 100644 --- a/actions/ansible-docs-build-init/action.yml +++ b/actions/ansible-docs-build-init/action.yml @@ -55,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" @@ -76,13 +77,13 @@ runs: echo "::endgroup::" fi - if [[ "${{ inputs.provide-link-targets }}" != "" ]]; then + 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 <<< "${{ inputs.provide-link-targets }}" + 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 From 12f434a4ff1b9bac274b213664b53a664f1b7c11 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 18 Jun 2022 20:04:08 +0200 Subject: [PATCH 4/8] Add tests. --- .github/workflows/test-action-build-init.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml index f22f75f..539eaab 100644 --- a/.github/workflows/test-action-build-init.yml +++ b/.github/workflows/test-action-build-init.yml @@ -35,11 +35,16 @@ jobs: fail-on-error: - true - false + provide-links-safely: + - | + 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-links-safely: '' steps: - name: Checkout @@ -66,6 +71,7 @@ jobs: skip-init: ${{ matrix.skip-init }} antsibull-docs-version: ${{ matrix.antsibull-docs-version }} lenient: ${{ matrix.lenient }} + provide-links-safely: ${{ matrix.provide-links-safely }} - name: assert env: @@ -102,3 +108,10 @@ 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-links-safely was used + # :orphan: and the labels mentioned in provide-links-safely should end up in rst/_targets.rst + # short circuit if skip-init is 'true' + ${{ matrix.skip-init }} || grep -- '^:orphan:$' rst/_targets.rst || exit 1 + ${{ matrix.skip-init }} || grep -- '^.. _outside_reference_1:$' rst/_targets.rst || exit 1 + ${{ matrix.skip-init }} || grep -- '^.. _outside_reference_2:$' rst/_targets.rst || exit 1 From 9ec8a435b787c0db4b92cf74ef145ed6eaf4572e Mon Sep 17 00:00:00 2001 From: Brian Scholer <1260690+briantist@users.noreply.github.com> Date: Sat, 18 Jun 2022 17:15:59 -0400 Subject: [PATCH 5/8] Update .github/workflows/test-action-build-init.yml --- .github/workflows/test-action-build-init.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml index 539eaab..8982874 100644 --- a/.github/workflows/test-action-build-init.yml +++ b/.github/workflows/test-action-build-init.yml @@ -71,7 +71,7 @@ jobs: skip-init: ${{ matrix.skip-init }} antsibull-docs-version: ${{ matrix.antsibull-docs-version }} lenient: ${{ matrix.lenient }} - provide-links-safely: ${{ matrix.provide-links-safely }} + provide-link-targets: ${{ matrix.provide-links-safely }} - name: assert env: From de39eb4c3501754f14e7414c9391130054e0aa36 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 18 Jun 2022 23:25:30 +0200 Subject: [PATCH 6/8] Fix more copy'n'paste errors. --- .github/workflows/test-action-build-init.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml index 8982874..67b6bab 100644 --- a/.github/workflows/test-action-build-init.yml +++ b/.github/workflows/test-action-build-init.yml @@ -35,7 +35,7 @@ jobs: fail-on-error: - true - false - provide-links-safely: + provide-link-targets: - | outside_reference_1 outside_reference_2 @@ -44,7 +44,7 @@ jobs: dest: .test/simple-build lenient: false # unused but needs a value fail-on-error: false # unused but needs a value - provide-links-safely: '' + provide-link-targets: '' steps: - name: Checkout @@ -71,7 +71,7 @@ jobs: skip-init: ${{ matrix.skip-init }} antsibull-docs-version: ${{ matrix.antsibull-docs-version }} lenient: ${{ matrix.lenient }} - provide-link-targets: ${{ matrix.provide-links-safely }} + provide-link-targets: ${{ matrix.provide-link-targets }} - name: assert env: @@ -109,8 +109,8 @@ jobs: # 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-links-safely was used - # :orphan: and the labels mentioned in provide-links-safely should end up in rst/_targets.rst + # check if provide-link-targets was used + # :orphan: and the labels mentioned in provide-link-targets should end up in rst/_targets.rst # short circuit if skip-init is 'true' ${{ matrix.skip-init }} || grep -- '^:orphan:$' rst/_targets.rst || exit 1 ${{ matrix.skip-init }} || grep -- '^.. _outside_reference_1:$' rst/_targets.rst || exit 1 From 8d376978132dbfe3c030303e2565332a23cba043 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 20 Jun 2022 08:20:47 +0200 Subject: [PATCH 7/8] Try to improve tests. --- .github/workflows/test-action-build-init.yml | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml index 67b6bab..4ba7190 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 }}, provide-link-targets=${{ matrix.provide-link-targets }}] runs-on: ubuntu-latest strategy: fail-fast: false @@ -36,6 +36,7 @@ jobs: - true - false provide-link-targets: + - '' - | outside_reference_1 outside_reference_2 @@ -109,9 +110,13 @@ jobs: # 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 + # 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' - ${{ matrix.skip-init }} || grep -- '^:orphan:$' rst/_targets.rst || exit 1 - ${{ matrix.skip-init }} || grep -- '^.. _outside_reference_1:$' rst/_targets.rst || exit 1 - ${{ matrix.skip-init }} || grep -- '^.. _outside_reference_2:$' rst/_targets.rst || exit 1 + # 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 From 699d8f7ddc8c98b1d46199701429ac3fd032aa04 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 20 Jun 2022 08:33:17 +0200 Subject: [PATCH 8/8] Show as bool. --- .github/workflows/test-action-build-init.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml index 4ba7190..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 }}, provide-link-targets=${{ matrix.provide-link-targets }}] + 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