From a3a305f1affad88a1581313a9e84b5a1f1e528be Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Fri, 19 Jan 2024 21:41:41 +0100
Subject: [PATCH] Allow to append something to conf.py.

---
 .github/workflows/_shared-docs-build-pr.yml   |  7 +++++++
 .github/workflows/_shared-docs-build-push.yml |  6 ++++++
 .github/workflows/test-action-build-init.yml  |  9 +++++++++
 actions/ansible-docs-build-init/action.yml    | 14 ++++++++++++++
 4 files changed, 36 insertions(+)

diff --git a/.github/workflows/_shared-docs-build-pr.yml b/.github/workflows/_shared-docs-build-pr.yml
index c92a6e4..79b484b 100644
--- a/.github/workflows/_shared-docs-build-pr.yml
+++ b/.github/workflows/_shared-docs-build-pr.yml
@@ -99,6 +99,11 @@ on:
           `conf.py` in `html_theme_options`
         required: false
         type: string
+      init-extra-conf-py:
+        description: |
+          If provided, this text will be appended to the generated `conf.py` as-is.
+        required: false
+        type: string
       artifact-name:
         description: The name of the artifact to upload.
         required: false
@@ -312,6 +317,7 @@ jobs:
           extra-conf: ${{ inputs.init-extra-conf }}
           extra-html-context: ${{ inputs.init-extra-html-context }}
           extra-html-theme-options: ${{ inputs.init-extra-html-theme-options }}
+          extra-conf-py: ${{ inputs.init-extra-conf-py }}
 
       - name: Build BASE
         id: build-base
@@ -356,6 +362,7 @@ jobs:
           extra-conf: ${{ inputs.init-extra-conf }}
           extra-html-context: ${{ inputs.init-extra-html-context }}
           extra-html-theme-options: ${{ inputs.init-extra-html-theme-options }}
+          extra-conf-py: ${{ inputs.init-extra-conf-py }}
 
       - name: Build HEAD
         id: build-head
diff --git a/.github/workflows/_shared-docs-build-push.yml b/.github/workflows/_shared-docs-build-push.yml
index 4931ddb..0c55eb3 100644
--- a/.github/workflows/_shared-docs-build-push.yml
+++ b/.github/workflows/_shared-docs-build-push.yml
@@ -101,6 +101,11 @@ on:
           `conf.py` in `html_theme_options`
         required: false
         type: string
+      init-extra-conf-py:
+        description: |
+          If provided, this text will be appended to the generated `conf.py` as-is.
+        required: false
+        type: string
       artifact-upload:
         description: Whether or not to upload the build as an artifact.
         type: boolean
@@ -230,6 +235,7 @@ jobs:
           extra-conf: ${{ inputs.init-extra-conf }}
           extra-html-context: ${{ inputs.init-extra-html-context }}
           extra-html-theme-options: ${{ inputs.init-extra-html-theme-options }}
+          extra-conf-py: ${{ inputs.init-extra-conf-py }}
 
       - name: Build
         id: build
diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml
index e2c32e8..348f11e 100644
--- a/.github/workflows/test-action-build-init.yml
+++ b/.github/workflows/test-action-build-init.yml
@@ -59,6 +59,8 @@ jobs:
           - ''
         extra-html-theme-options:
           - ''
+        extra-conf-py:
+          - ''
         intersphinx-links: ['']
         squash-hierarchy:
           - false
@@ -100,6 +102,9 @@ jobs:
             extra-html-theme-options: |
               foo=baz
               long=Yet "another" long 'quotes' text
+            extra-conf-py: |
+              # This is a special comment.
+              # FOO BAR 1234
 
     steps:
       - name: Checkout
@@ -137,6 +142,7 @@ jobs:
           extra-conf: ${{ matrix.extra-conf }}
           extra-html-context: ${{ matrix.extra-html-context }}
           extra-html-theme-options: ${{ matrix.extra-html-theme-options }}
+          extra-conf-py: ${{ matrix.extra-conf-py }}
 
       - name: assert
         env:
@@ -233,5 +239,8 @@ jobs:
           # TODO Check extra-html-context
           # TODO Check extra-html-theme-options
 
+          ${{ matrix.extra-conf-py && 'true' || 'false' }} && (grep -E '^# This is a special comment$' conf.py || exit 1)
+          ${{ matrix.extra-conf-py && 'true' || 'false' }} && (grep -E '^# FOO BAR 1234$' conf.py || exit 1)
+
           # This must be the last line
           exit 0
diff --git a/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml
index 6c0f443..d4cf743 100644
--- a/actions/ansible-docs-build-init/action.yml
+++ b/actions/ansible-docs-build-init/action.yml
@@ -97,6 +97,10 @@ inputs:
       A newline separated list of `key=value` entries that will be added to the generated
       `conf.py` in `html_theme_options`
     required: false
+  append-conf-py:
+    description: |
+      If provided, this text will be appended to the generated `conf.py` as-is.
+    required: false
 outputs:
   build-script:
     description: The path of the build script to execute.
@@ -121,6 +125,7 @@ runs:
         _INPUT_EXTRA_CONF: ${{ inputs.extra-conf }}
         _INPUT_EXTRA_HTML_CONTEXT: ${{ inputs.extra-html-context }}
         _INPUT_EXTRA_HTML_THEME_OPTIONS: ${{ inputs.extra-html-theme-options }}
+        _INPUT_APPEND_CONF_PY: ${{ inputs.append-conf-py }}
       shell: bash
       run: |
         echo "::group::Installing antsibull-docs"
@@ -229,6 +234,15 @@ runs:
             echo "::endgroup::"
         fi
 
+        if [[ "${_INPUT_APPEND_CONF_PY}" != "" ]]; then
+            echo "::group::Appending to conf.py"
+            echo "${_INPUT_APPEND_CONF_PY}" >> {{ inputs.dest-dir }}/conf.py
+            echo "Content of ${{ inputs.dest-dir }}/conf.py:"
+            echo ""
+            cat "{{ inputs.dest-dir }}/conf.py"
+            echo "::endgroup::"
+        fi
+
         echo "::group::Install additional requirements"
         pip install -r "${{ inputs.dest-dir }}/requirements.txt"
         echo "::endgroup::"