Allow to provide extra labels (#43)

* Allow to provide extra labels.

* Change to use newlines instead of commas to separate entries.

* Use input.provide-link-targets safely.

* Add tests.

* Update .github/workflows/test-action-build-init.yml

* Fix more copy'n'paste errors.

* Try to improve tests.

* Show as bool.

Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>

Author: felixfontein

.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

.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

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::"