Merge branch 'ansible:devel' into patch-1

.codespellignorelines

@@ -0,0 +1,19 @@
+# This file contains exact lines ignored by the spelling check.
+   $ ssh-add ~/.ssh/keypair.pem
+     shell: echo "disable server myapplb/{{ inventory_hostname }}" | socat stdio /var/lib/haproxy/stats
+     shell: echo "enable server myapplb/{{ inventory_hostname }}" | socat stdio /var/lib/haproxy/stats
+            "ro": true,
+                "options": "ro,relatime,mode=0700",
+        RootSDDL = O:NSG:BAD:P(A;;GA;;;BA)(A;;GR;;;IU)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD)
+IAM policies for AWS
+    for managing IAM roles, users and groups.
+see the `Active Directory Certificate Services documentation <https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc732625(v=ws.11)>`_.
+  `Act as part of the operating system <https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn221957(v=ws.11)>`_.
+`Accounts: Limit local account use of blank passwords to console logon only <https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/jj852174(v=ws.11)>`_
+        role_type: ANS
+    # => "$6$43927$lQxPKz2M2X.NWO.gK.t7phLwOKQMcSq72XxDZQ0XzYV6DlL1OD72h417aj16OnHTGxNzhftXJQBcjbunLEepM0"
+    table#network-platform-table thead tr th.head {
+# Following lines from the generated file docs/docsite/rst/reference_appendices/config.rst
+:Description: This setting changes the behaviour of mismatched host patterns, it allows you to force a fatal error, a warning or just ignore it.
+    This setting changes the behaviour of mismatched host patterns, it allows you to force a fatal error, a warning or just ignore it.
+   /msg alis LIST #ansible* -min 5

.codespellignorewords

@@ -0,0 +1,4 @@
+# This file contains words ignored by the spelling check.
+aci
+falsy
+doas

.codespellrc

@@ -0,0 +1,8 @@
+[codespell]
+skip = _build,collections,*.po,_static,porting_guide*,style_guide,*.inv
+count =
+check-filenames = true
+quiet-level = 3
+ignore-words = .codespellignorewords
+exclude-file = .codespellignorelines
+builtin = clear,code,en-GB_to_en-US,informal,names,rare

.github/workflows/build-package-docs.yaml

@@ -0,0 +1,239 @@
+---
+
+name: Ansible package docs build
+on:
+  schedule:
+    - cron: '17 5 * * *' # Run at 05:17 am
+  workflow_dispatch:
+    inputs:
+      repository-owner:
+        description: GitHub account or org that owns the repository
+        required: true
+        default: ansible
+      repository-name:
+        description: Name of the GitHub repository
+        required: true
+        default: ansible-documentation
+      repository-branch:
+        description: Branch, tag, or commit SHA
+        required: true
+        default: devel
+      ansible-package-version:
+        type: choice
+        description: Ansible community package version
+        required: true
+        default: devel
+        options:
+        - devel
+        - '11'
+        - '10'
+        - '9'
+      deploy:
+        type: boolean
+        description: Deploy the build
+        required: true
+      deployment-environment:
+        type: choice
+        description: Deployment environment
+        required: true
+        default: test
+        options:
+        - production
+        - test
+
+env:
+  PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version || 'devel' }}
+
+jobs:
+  build-package-docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout Ansible documentation
+      uses: actions/checkout@v4
+      with:
+        repository: >-
+          ${{
+            github.event.inputs.repository-owner || 'ansible'
+          }}/${{
+            github.event.inputs.repository-name || 'ansible-documentation'
+          }}
+        ref: ${{ github.event.inputs.repository-branch || 'devel' }}
+        path: build-directory
+
+    - name: Setup nox
+      uses: wntrblm/nox@2024.04.15
+
+    - name: Output Python info
+      run: python --version --version && which python
+
+    - name: Graft ansible-core
+      run: nox -s clone-core
+      working-directory: build-directory
+
+    - name: Install project requirements
+      run: >-
+        python -m pip install
+        -r tests/requirements.in
+        -c tests/requirements.txt
+      working-directory: build-directory
+
+    - name: Set the COLLECTION_LIST variable
+      if: env.PACKAGE_VERSION != 'devel'
+      run: >-
+        echo COLLECTION_LIST="${PACKAGE_VERSION}"
+        >> "${GITHUB_ENV}"
+
+    - name: Set the VERSION variable
+      run: echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}"
+
+    - name: Build the Ansible community package docs
+      run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}"
+      working-directory: build-directory/docs/docsite
+
+    - name: Create a tarball with the build contents
+      run: >-
+        tar -czvf
+        ansible-package-docs-html-"${PACKAGE_VERSION}"-"$(date '+%Y-%m-%d')"-${{
+          github.run_id
+        }}-${{
+          github.run_number
+        }}-${{
+          github.run_attempt
+        }}.tar.gz
+        --directory=_build/html/ .
+      working-directory: build-directory/docs/docsite
+
+    - name: Create a downloadable archive that contains the tarball
+      uses: actions/upload-artifact@v4
+      with:
+        name: package-docs-build
+        path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz
+        retention-days: 7
+
+  check-deploy:
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.deploy == 'true'
+    needs: build-package-docs
+    runs-on: ubuntu-latest
+    steps:
+    - name: Log the workflow inputs if deployed
+      run: |
+        {
+          echo "## Deployment details :shipit:";
+          echo "Publish to: ${{ github.event.inputs.deployment-environment }}";
+          echo "Package version: ${{ github.event.inputs.ansible-package-version }}";
+          echo "Owner: ${{ github.event.inputs.repository-owner }}";
+          echo "Branch: ${{ github.event.inputs.repository-branch }}";
+        } >> "${GITHUB_STEP_SUMMARY}"
+
+  notify-build-failures:
+    if: failure()
+    needs: build-package-docs
+    runs-on: ubuntu-latest
+    env:
+      ROOM_URL: https://ansible-accounts.ems.host/_matrix/client/v3/rooms/!HJtetIFWYEIDBOXxFE:libera.chat/send/m.room.message
+      FAIL_MESSAGE: >-
+          Oh no! A community package docs build has failed.
+          Check this workflow run to see what went wrong:
+          https://github.com/ansible/ansible-documentation/actions/runs/${{ github.run_id }}
+          @orandon @samccann
+    steps:
+    - name: Set a transaction ID
+      run: echo "TX_ID=$(date +%s)" >> "${GITHUB_ENV}"
+
+    - name: Notify the DaWGs in Matrix
+      run: |
+        curl -X PUT "${{ env.ROOM_URL }}/${TX_ID}" \
+             -H "Authorization: Bearer ${{ secrets.DOCS_BOT_TOKEN }}" \
+             -H "Content-Type: application/json" \
+             -d '{"msgtype": "m.text", "body": "${{ env.FAIL_MESSAGE }}"}'
+
+  deploy-package-docs:
+    needs:
+      - check-deploy
+    runs-on: ubuntu-latest
+    environment:
+      name: deploy-package-docs
+      url: ${{ env.ENV_URL }}
+    env:
+      TARGET: ${{ github.event.inputs.deployment-environment }}
+      DEST_REPO: ansible-community/package-doc-builds
+      USER_EMAIL: "41898282+github-actions[bot]@users.noreply.github.com"
+      USER_NAME: "github-actions[bot]"
+    steps:
+    - name: Download the build archive
+      uses: actions/download-artifact@v4
+      with:
+        name: package-docs-build
+
+    - name: Extract the tarball
+      run: >-
+        tar -xvzf
+        ansible-package-docs-html-*.tar.gz
+        --one-top-level
+
+    - name: Set the production branch and url
+      if: env.TARGET == 'production'
+      env:
+        BRANCH_NAME: ${{ github.event.inputs.ansible-package-version }}
+        PROD_URL: https://ansible.readthedocs.io/projects/ansible
+      run: |
+        echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}"
+        echo "ENV_URL=${PROD_URL}/${BRANCH_NAME}" >> "${GITHUB_ENV}"
+
+    - name: Set the test branch and url
+      if: env.TARGET == 'test'
+      env:
+        TEST_URL: https://ansible-community.github.io/package-doc-builds
+      run: |
+        echo "BRANCH=gh-pages" >> "${GITHUB_ENV}"
+        echo "ENV_URL=${TEST_URL}" >> "${GITHUB_ENV}"
+
+    - name: Checkout the deploy directory
+      uses: actions/checkout@v4
+      with:
+        repository: ${{ env.DEST_REPO }}
+        ref: ${{ env.BRANCH }}
+        path: deploy-directory
+        fetch-depth: 0
+        ssh-key: ${{ secrets.DEPLOY_DOC_BUILD }}
+        persist-credentials: true
+
+    - name: Copy the generated HTML and assets for production
+      run: >-
+        rsync -av --delete --mkpath
+        ansible-package-docs-html-*/
+        deploy-directory/docs
+
+    - name: Create a norobots.txt file for the test site
+      if: env.TARGET == 'test'
+      run: |
+        touch norobots.txt
+        echo "User-agent: *" > norobots.txt
+        echo "Disallow: /" >> norobots.txt
+      working-directory: deploy-directory/docs
+
+    - name: Configure the git user
+      run: |
+        git config --local user.email "${USER_EMAIL}"
+        git config --local user.name "${USER_NAME}"
+      working-directory: deploy-directory
+
+    - name: Git add the generated HTML and assets
+      run: git add ./docs --all --force
+      working-directory: deploy-directory
+
+    - name: Commit generated HTML and assets
+      run: >-
+        git diff-index --quiet HEAD ||
+        git commit -m "Push docs build $(date '+%Y-%m-%d')-${{
+          github.run_id
+        }}-${{
+           github.run_number
+        }}-${{
+          github.run_attempt
+        }}"
+      working-directory: deploy-directory
+
+    - name: Push build to deploy repository
+      run: git push origin
+      working-directory: deploy-directory

.github/workflows/ci.yaml

@@ -1,6 +1,9 @@
 name: Ansible Docsite CI
 
 on:
+  schedule:
+    # Daily 
+    - cron: "23 7 * * *"
   push:
     branches-ignore:
       - 'patchback/**'
@@ -9,53 +12,19 @@ on:
   workflow_dispatch:
 
 jobs:
-  docs_sanity_docs_build:
-    name: docs-build
-    runs-on: ubuntu-22.04
-    steps:
-    - name: Checkout Docsite
-      uses: actions/checkout@v4
-
-    - name: Install Python 3.11
-      uses: actions/setup-python@v4
-      with:
-        python-version: '3.11'
+  nox:
+    uses: ./.github/workflows/reusable-nox.yml
 
-    - name: Install Test Requirements
-      run: |
-        python -m pip install -r tests/requirements.in -c tests/requirements.txt
+  check:
+    if: always()
 
-    - name: Graft ansible-core
-      run: |
-        python docs/bin/clone-core.py
+    needs:
+      - nox
 
-    - name: Run docs-build Sanity
-      run: |
-        python tests/sanity.py docs-build
+    runs-on: ubuntu-latest
 
-  docs_sanity_rstcheck:
-    name: rstcheck
-    runs-on: ubuntu-22.04
     steps:
-    - name: Checkout Docsite
-      uses: actions/checkout@v4
-
-    - name: Install Python 3.11
-      uses: actions/setup-python@v4
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
       with:
-        python-version: '3.11'
-
-    - name: Install Test Requirements
-      run: |
-        python -m pip install -r tests/requirements.in -c tests/requirements.txt
-
-    - name: Graft ansible-core
-      run: |
-        python docs/bin/clone-core.py
-
-    - name: Run rstcheck Sanity
-      run: |
-        python tests/sanity.py rstcheck
-
-  nox:
-    uses: ./.github/workflows/reusable-nox.yml
+        jobs: ${{ toJSON(needs) }}