build-init - lenient, fail-on-error, antsibull-version (#27)

briantist · web-flow · commit c2e93975f7e8 · 2022-02-05T20:38:09.000-05:00
* add antsibull-version option for build-init

* use the option!

* no really, use the option tho

* add lenient mode

* do not split param name and value

* fix matrix, try better names

* short circuit lenient test when skip-init

* add fail-on-error

* test fixes

* show antsibull version

* add new option pass-throughs to shared workflows
diff --git a/.github/workflows/_shared-docs-build-pr.yml b/.github/workflows/_shared-docs-build-pr.yml
@@ -26,6 +26,22 @@ on:
         description: A directory relative to the checkout where the init process has already been run.
         required: false
         type: string
+      init-lenient:
+        description: Use the lenient option during build init. Has no effect if init-dest-dir is supplied.
+        required: false
+        type: boolean
+        default: false
+      init-fail-on-error:
+        description: Use the fail-on-error option during build init. Has no effect if init-dest-dir is supplied.
+        required: false
+        type: boolean
+        default: false
+      init-antsibull-version:
+        description: |
+          The version of antsibull to use during build init. Has no effect if init-dest-dir is supplied.
+          If not supplied, the latest version from PyPI is used. If supplied, must be a git ref from the antsibull repository.
+        required: false
+        type: string
       artifact-name:
         description: The name of the artifact to upload.
         required: false
@@ -193,6 +209,9 @@ jobs:
           collections: ${{ inputs.collection-name }}
           dest-dir: ${{ steps.vars.outputs.init-dir-base }}
           skip-init: ${{ steps.vars.outputs.skip-init }}
+          antsibull-version: '${{ inputs.init-antsibull-version }}'
+          lenient: ${{ inputs.init-lenient }}
+          fail-on-error: ${{ inputs.init-fail-on-error }}
 
       - name: Build BASE
         id: build-base
@@ -222,6 +241,9 @@ jobs:
           collections: ${{ inputs.collection-name }}
           dest-dir: ${{ steps.vars.outputs.init-dir-head }}
           skip-init: ${{ steps.vars.outputs.skip-init }}
+          antsibull-version: '${{ inputs.init-antsibull-version }}'
+          lenient: ${{ inputs.init-lenient }}
+          fail-on-error: ${{ inputs.init-fail-on-error }}
 
       - name: Build HEAD
         id: build-head
diff --git a/.github/workflows/_shared-docs-build-push.yml b/.github/workflows/_shared-docs-build-push.yml
@@ -26,6 +26,22 @@ on:
         description: A directory relative to the checkout where the init process has already been run.
         required: false
         type: string
+      init-lenient:
+        description: Use the lenient option during build init. Has no effect if init-dest-dir is supplied.
+        required: false
+        type: boolean
+        default: false
+      init-fail-on-error:
+        description: Use the fail-on-error option during build init. Has no effect if init-dest-dir is supplied.
+        required: false
+        type: boolean
+        default: false
+      init-antsibull-version:
+        description: |
+          The version of antsibull to use during build init. Has no effect if init-dest-dir is supplied.
+          If not supplied, the latest version from PyPI is used. If supplied, must be a git ref from the antsibull repository.
+        required: false
+        type: string
       artifact-name:
         description: The name of the artifact to upload.
         required: false
@@ -105,6 +121,9 @@ jobs:
           collections: ${{ steps.vars.outputs.col-name }}
           dest-dir: ${{ steps.vars.outputs.init-dir }}
           skip-init: ${{ steps.vars.outputs.skip-init }}
+          antsibull-version: '${{ inputs.init-antsibull-version }}'
+          lenient: ${{ inputs.init-lenient }}
+          fail-on-error: ${{ inputs.init-fail-on-error }}
 
       - name: Build
         id: build
diff --git a/.github/workflows/test-action-build-init.yml b/.github/workflows/test-action-build-init.yml
@@ -14,7 +14,7 @@ on:
 
 jobs:
   tests:
-    name: Init tests
+    name: Init [ver=${{ matrix.antsibull-version }}, skip=${{ matrix.skip-init }}, lenient=${{ matrix.lenient }}, fail-on-error=${{ matrix.fail-on-error }}, dest=${{ matrix.dest }}, collections=${{ matrix.collections }}]
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -25,9 +25,20 @@ jobs:
           - 'fake.collection'
           - 'first.collection second.collection'
         dest: ['']
+        antsibull-version:
+          - ''  # there is no default so this will be ok
+          - main
+        lenient:
+          - true
+          - false
+        fail-on-error:
+          - true
+          - 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
 
     steps:
       - name: Checkout
@@ -52,6 +63,8 @@ jobs:
           # please keep in sync!
           dest-dir: ${{ matrix.dest || format('{0}/{1}', runner.temp, '/docsbuild') }}
           skip-init: ${{ matrix.skip-init }}
+          antsibull-version: ${{ matrix.antsibull-version }}
+          lenient: ${{ matrix.lenient }}
 
       - name: assert
         env:
@@ -76,3 +89,15 @@ jobs:
           pip freeze > "${{ runner.temp }}/post-freeze.txt"
 
           cmp "${{ runner.temp }}/pre-freeze.txt" "${{ runner.temp }}/post-freeze.txt" || exit 1
+
+          # check if lenient mode was used
+          # if lenient == 'true', the grep should fail and end up running the true command
+          # if lenient == 'false', the grep should succeed and never run the false command
+          # short circuit if skip-init is 'true'
+          ${{ matrix.skip-init }} || grep -- '^nitpicky = True$' conf.py || ${{ matrix.lenient }} || exit 1
+
+          # check if fail-on-error mode was used
+          # if fail-on-error == 'true', the grep should fail (!succeed) and end up running the true command
+          # 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
diff --git a/actions/ansible-docs-build-init/action.yml b/actions/ansible-docs-build-init/action.yml
@@ -18,6 +18,24 @@ inputs:
       antsibull and the contents of the requirements.txt file in dest-dir.
     required: false
     default: 'false'
+  fail-on-error:
+    description: |
+      Corresponds to the --fail-on-error flag in antsibull. Fails if plugins cannot be parsed.
+      Has no effect if skip-init is true.
+    required: false
+    default: 'false'
+  lenient:
+    description: |
+      Corresponds to the --lenient flag for antsibull sphinx-init.
+      By default, the build process will fail on warnings unless this is set to 'true'.
+      Has no effect if skip-init is true.
+    required: false
+    default: 'false'
+  antsibull-version:
+    description: |
+      The version of antsibull 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
 outputs:
   build-script:
     description: The path of the build script to execute.
@@ -31,10 +49,17 @@ runs:
   steps:
     - name: Install Antsibull and Initialize Sphinx
       id: init
+      env:
+        PIP_DISABLE_PIP_VERSION_CHECK: '1'
       shell: bash
       run: |
         echo "::group::Installing Antsibull"
-        pip install antsibull --disable-pip-version-check
+        if [[ "${{ inputs.antsibull-version }}" != "" ]] ; then
+            pip install https://github.com/ansible-community/antsibull/archive/${{ inputs.antsibull-version }}.tar.gz
+        else
+            pip install antsibull
+        fi
+        antsibull-docs --version
         echo "::endgroup::"
 
         if [[ "${{ inputs.skip-init }}" != "true" ]] ; then
@@ -43,12 +68,12 @@ runs:
             echo "::endgroup::"
 
             echo "::group::Initialize Sphinx"
-            antsibull-docs sphinx-init --use-current --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 }}
             echo "::endgroup::"
         fi
 
         echo "::group::Install additional requirements"
-        pip install -r "${{ inputs.dest-dir }}/requirements.txt" --disable-pip-version-check
+        pip install -r "${{ inputs.dest-dir }}/requirements.txt"
         echo "::endgroup::"
 
         echo "::set-output name=build-script::${{ inputs.dest-dir }}/build.sh"
