Support adding intersphinx links (#54)

* Support adding intersphinx links

* Add basic test

Author: tremble

.github/workflows/_shared-docs-build-pr.yml

@@ -108,6 +108,13 @@ on:
         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
+      intersphinx-links:
+        description: |
+          A newline separated list of entries to add to the intersphinx_mapping in the generated conf.py.
+          Use the syntax `identifier:https://server/path` to add the identifier `identifier` with URL
+          `https://server/path`.
+        required: false
+        type: string
 
     outputs:
       artifact-name:
@@ -234,6 +241,7 @@ jobs:
           lenient: true
           fail-on-error: false
           provide-link-targets: ${{ inputs.provide-link-targets }}
+          intersphinx-links: ${{ inputs.intersphinx-links }}
 
       - name: Build BASE
         id: build-base
@@ -267,6 +275,7 @@ jobs:
           lenient: ${{ inputs.init-lenient }}
           fail-on-error: ${{ inputs.init-fail-on-error }}
           provide-link-targets: ${{ inputs.provide-link-targets }}
+          intersphinx-links: ${{ inputs.intersphinx-links }}
 
       - name: Build HEAD
         id: build-head

.github/workflows/_shared-docs-build-push.yml

@@ -66,6 +66,13 @@ on:
         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
+      intersphinx-links:
+        description: |
+          A newline separated list of entries to add to the intersphinx_mapping in the generated conf.py.
+          Use the syntax `identifier:https://server/path` to add the identifier `identifier` with URL
+          `https://server/path`.
+        required: false
+        type: string
 
     outputs:
       artifact-name:
@@ -152,6 +159,7 @@ jobs:
           lenient: ${{ inputs.init-lenient }}
           fail-on-error: ${{ inputs.init-fail-on-error }}
           provide-link-targets: ${{ inputs.provide-link-targets }}
+          intersphinx-links: ${{ inputs.intersphinx-links }}
 
       - name: Build
         id: build

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

@@ -17,7 +17,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 }}, 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 != '' }}], intersphinx-links=${{ matrix.intersphinx-links }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -43,12 +43,20 @@ jobs:
           - |
             outside_reference_1
             outside_reference_2
+        intersphinx-links: ['']
         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: ''
+          - 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/
 
     steps:
       - name: Checkout
@@ -76,6 +84,7 @@ jobs:
           antsibull-docs-version: ${{ matrix.antsibull-docs-version }}
           lenient: ${{ matrix.lenient }}
           provide-link-targets: ${{ matrix.provide-link-targets }}
+          intersphinx-links: ${{ matrix.intersphinx-links }}
 
       - name: assert
         env:
@@ -121,6 +130,13 @@ jobs:
           ${{ 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 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

@@ -40,6 +40,13 @@ inputs:
     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
+  intersphinx-links:
+    description: |
+      A newline separated list of entries to add to the intersphinx_mapping in the generated conf.py.
+      Use the syntax `identifier:https://server/path` to add the identifier `identifier` with URL
+      `https://server/path`.
+    required: false
+    type: string
 outputs:
   build-script:
     description: The path of the build script to execute.
@@ -56,6 +63,7 @@ runs:
       env:
         PIP_DISABLE_PIP_VERSION_CHECK: '1'
         _INPUT_PROVIDE_LINK_TARGETS: ${{ inputs.provide-link-targets }}
+        _INPUT_INTERSPHINX_LINKS: ${{ inputs.intersphinx-links }}
       shell: bash
       run: |
         echo "::group::Installing antsibull-docs"
@@ -72,8 +80,21 @@ runs:
             mkdir -p "${{ inputs.dest-dir }}"
             echo "::endgroup::"
 
+            INTERSPHINX_ARGS=()
+
+            if [[ "${_INPUT_INTERSPHINX_LINKS}" != "" ]]; then
+                echo "::group::Building list of intersphinx links"
+                while read -r line; do
+                    if [ "${line}" != "" ]; then
+                        INTERSPHINX_ARGS+=("--intersphinx" "${line}")
+                    fi
+                done <<< "${_INPUT_INTERSPHINX_LINKS}"
+                echo "Intersphinx args: ${INTERSPHINX_ARGS[@]}"
+                echo "::endgroup::"
+            fi
+
             echo "::group::Initialize Sphinx"
-            antsibull-docs sphinx-init --use-current ${{ fromJSON(inputs.fail-on-error) && '--fail-on-error' || '' }} ${{ fromJSON(inputs.lenient) && '--lenient' || '' }} --dest-dir "${{ inputs.dest-dir }}" ${{ inputs.collections }}
+            antsibull-docs sphinx-init --use-current ${{ fromJSON(inputs.fail-on-error) && '--fail-on-error' || '' }} ${{ fromJSON(inputs.lenient) && '--lenient' || '' }} --dest-dir "${{ inputs.dest-dir }}" ${{ inputs.collections }} ${INTERSPHINX_ARGS[@]}
             echo "::endgroup::"
         fi