From 2fd8c7de4bbb7188aacbc7b5b376551a6762c166 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 23 Nov 2022 23:26:12 +0100 Subject: [PATCH 1/5] Allow to pass --squash-hierarchy to 'antsibull-docs sphinx-init'. --- .github/workflows/_shared-docs-build-pr.yml | 8 ++++++++ .github/workflows/_shared-docs-build-push.yml | 7 +++++++ .github/workflows/test-action-build-init.yml | 14 ++++++++++++++ actions/ansible-docs-build-init/action.yml | 8 +++++++- 4 files changed, 36 insertions(+), 1 deletion(-) diff --git a/.github/workflows/_shared-docs-build-pr.yml b/.github/workflows/_shared-docs-build-pr.yml index 45ed821..ce2295c 100644 --- a/.github/workflows/_shared-docs-build-pr.yml +++ b/.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 diff --git a/.github/workflows/_shared-docs-build-push.yml b/.github/workflows/_shared-docs-build-push.yml index 6dcb5b4..f829f2b 100644 --- a/.github/workflows/_shared-docs-build-push.yml +++ b/.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 diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml index 9d96796..156247b 100644 --- a/.github/workflows/test-action-build-init.yml +++ b/.github/workflows/test-action-build-init.yml @@ -44,12 +44,15 @@ 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 @@ -57,6 +60,13 @@ jobs: 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 @@ -85,6 +95,7 @@ jobs: lenient: ${{ matrix.lenient }} provide-link-targets: ${{ matrix.provide-link-targets }} intersphinx-links: ${{ matrix.intersphinx-links }} + squash-hierarchy: ${{ matrix.squash-hierarchy }} - name: assert env: @@ -137,6 +148,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 diff --git a/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml index d01dbbd..b56d0a0 100644 --- a/actions/ansible-docs-build-init/action.yml +++ b/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 From 63ca189ddf6536abb98930a62b6224e8675838d7 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 23 Nov 2022 23:32:34 +0100 Subject: [PATCH 2/5] Improve/fix tests. --- .github/workflows/test-action-build-init.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml index 156247b..4357c48 100644 --- a/.github/workflows/test-action-build-init.yml +++ b/.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 @@ -102,6 +102,8 @@ jobs: 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 @@ -149,7 +151,7 @@ jobs: ${{ 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 + ${{ 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 From 54713f188c4d7afbacef256ee30a458f213ddd1f Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 23 Nov 2022 23:37:13 +0100 Subject: [PATCH 3/5] TMP debug --- actions/ansible-docs-build-init/action.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml index b56d0a0..f5b6989 100644 --- a/actions/ansible-docs-build-init/action.yml +++ b/actions/ansible-docs-build-init/action.yml @@ -100,6 +100,7 @@ runs: fi echo "::group::Initialize Sphinx" + echo 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[@]} 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 From 09a520cbc8ca5d152a3f4b92e71e21243bb0aa05 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 23 Nov 2022 23:42:28 +0100 Subject: [PATCH 4/5] Fix bug in tests. --- .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 4357c48..e2f0409 100644 --- a/.github/workflows/test-action-build-init.yml +++ b/.github/workflows/test-action-build-init.yml @@ -86,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') }} From af59676f76c438b2f9b781226951d2463efdd30f Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 23 Nov 2022 23:42:33 +0100 Subject: [PATCH 5/5] Revert "TMP debug" This reverts commit 54713f188c4d7afbacef256ee30a458f213ddd1f. --- actions/ansible-docs-build-init/action.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml index f5b6989..b56d0a0 100644 --- a/actions/ansible-docs-build-init/action.yml +++ b/actions/ansible-docs-build-init/action.yml @@ -100,7 +100,6 @@ runs: fi echo "::group::Initialize Sphinx" - echo 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[@]} 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