Allow to pass --squash-hierarchy to 'antsibull-docs sphinx-init' (#58)

* Allow to pass --squash-hierarchy to 'antsibull-docs sphinx-init'.

* Improve/fix tests.

* TMP debug

* Fix bug in tests.

* Revert "TMP debug"

This reverts commit 54713f1.

Author: felixfontein

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

@@ -115,6 +115,12 @@ on:
           `https://server/path`.
         required: false
         type: string
+      squash-hierarchy:
+        description: |
+          If 'true', the collection documentation will be created at top-level and not in a subdirectory `namespace/collection_name/`.
+          Has no effect if init-dest-dir is supplied.
+        required: false
+        default: 'false'
 
     outputs:
       artifact-name:
@@ -242,6 +248,7 @@ jobs:
           fail-on-error: false
           provide-link-targets: ${{ inputs.provide-link-targets }}
           intersphinx-links: ${{ inputs.intersphinx-links }}
+          squash-hierarchy: ${{ input.squash-hierarchy }}
 
       - name: Build BASE
         id: build-base
@@ -276,6 +283,7 @@ jobs:
           fail-on-error: ${{ inputs.init-fail-on-error }}
           provide-link-targets: ${{ inputs.provide-link-targets }}
           intersphinx-links: ${{ inputs.intersphinx-links }}
+          squash-hierarchy: ${{ input.squash-hierarchy }}
 
       - name: Build HEAD
         id: build-head

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

@@ -73,6 +73,12 @@ on:
           `https://server/path`.
         required: false
         type: string
+      squash-hierarchy:
+        description: |
+          If 'true', the collection documentation will be created at top-level and not in a subdirectory `namespace/collection_name/`.
+          Has no effect if init-dest-dir is supplied.
+        required: false
+        default: 'false'
 
     outputs:
       artifact-name:
@@ -160,6 +166,7 @@ jobs:
           fail-on-error: ${{ inputs.init-fail-on-error }}
           provide-link-targets: ${{ inputs.provide-link-targets }}
           intersphinx-links: ${{ inputs.intersphinx-links }}
+          squash-hierarchy: ${{ input.squash-hierarchy }}
 
       - 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 != '' }}], intersphinx-links=${{ matrix.intersphinx-links }}
+    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 }}, squash-hierarchy=${{ matrix.squash-hierarchy }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -44,19 +44,29 @@ jobs:
             outside_reference_1
             outside_reference_2
         intersphinx-links: ['']
+        squash-hierarchy:
+          - false
         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: ''
+            squash-hierarchy: false
           - 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/
+            squash-hierarchy: false
+          - skip-init: false
+            collections: foo.bar
+            dest: ''
+            lenient: false
+            fail-on-error: true
+            squash-hierarchy: true
 
     steps:
       - name: Checkout
@@ -76,7 +86,7 @@ jobs:
         id: init
         uses: ./actions/ansible-docs-build-init
         with:
-          collections: ${{ matrix.collection }}
+          collections: ${{ matrix.collections }}
           # combining runner.temp and /docsbuild copies the default from the action
           # please keep in sync!
           dest-dir: ${{ matrix.dest || format('{0}/{1}', runner.temp, '/docsbuild') }}
@@ -85,12 +95,15 @@ jobs:
           lenient: ${{ matrix.lenient }}
           provide-link-targets: ${{ matrix.provide-link-targets }}
           intersphinx-links: ${{ matrix.intersphinx-links }}
+          squash-hierarchy: ${{ matrix.squash-hierarchy }}
 
       - name: assert
         env:
           output_build_script: ${{ steps.init.outputs.build-script }}
           output_build_html: ${{ steps.init.outputs.build-html }}
         run: |
+          set -x
+
           # check that the build script exists
           [ -f "$output_build_script" ] || exit 1
 
@@ -137,6 +150,9 @@ jobs:
           ${{ 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 that the squash hierarchy flag was added
+          ${{ matrix.squash-hierarchy }} && (grep -q -- ' --squash-hierarchy ' build.sh || 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

@@ -47,6 +47,12 @@ inputs:
       `https://server/path`.
     required: false
     type: string
+  squash-hierarchy:
+    description: |
+      If 'true', the collection documentation will be created at top-level and not in a subdirectory `namespace/collection_name/`.
+      This is only possible if 'collections' contains exactly one collection.
+    required: false
+    default: 'false'
 outputs:
   build-script:
     description: The path of the build script to execute.
@@ -94,7 +100,7 @@ runs:
             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 }} ${INTERSPHINX_ARGS[@]}
+            antsibull-docs sphinx-init --use-current ${{ fromJSON(inputs.fail-on-error) && '--fail-on-error' || '' }} ${{ fromJSON(inputs.lenient) && '--lenient' || '' }} ${{ fromJSON(inputs.squash-hierarchy) && '--squash-hierarchy' || '' }} --dest-dir "${{ inputs.dest-dir }}" ${{ inputs.collections }} ${INTERSPHINX_ARGS[@]}
             echo "::endgroup::"
         fi