Skip to content

Commit 902f060

Browse files
oraNodfelixfontein
oraNod
and
felixfontein
authored
Restructure package docs workflow (#2348)
* fixes #2047 restructure package docs workflow This change splits the package docs workflow into reusable parts for flexibility so that we can run different builds on various schedules. --------- Co-authored-by: Felix Fontein <5781356+felixfontein@users.noreply.github.com>
1 parent fed75be commit 902f060

File tree

3 files changed

+277
-197
lines changed

3 files changed

+277
-197
lines changed

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

Lines changed: 28 additions & 197 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,29 @@
11
---
2-
3-
name: Ansible package docs build
2+
name: Build and deploy docs
43
on:
54
schedule:
6-
- cron: '17 5 * * *' # Run at 05:17 am
5+
# Run at 05:17 on Tuesday and Thursday
6+
- cron: '17 5 * * 2,4'
77
workflow_dispatch:
88
inputs:
99
repository-owner:
1010
description: GitHub account or org that owns the repository
11+
type: string
1112
required: true
1213
default: ansible
1314
repository-name:
1415
description: Name of the GitHub repository
16+
type: string
1517
required: true
1618
default: ansible-documentation
1719
repository-branch:
1820
description: Branch, tag, or commit SHA
21+
type: string
1922
required: true
2023
default: devel
2124
ansible-package-version:
22-
type: choice
2325
description: Ansible community package version
26+
type: choice
2427
required: true
2528
default: devel
2629
options:
@@ -29,211 +32,39 @@ on:
2932
- '10'
3033
- '9'
3134
deploy:
32-
type: boolean
3335
description: Deploy the build
36+
type: boolean
3437
required: true
3538
deployment-environment:
36-
type: choice
3739
description: Deployment environment
40+
type: choice
3841
required: true
3942
default: test
4043
options:
4144
- production
4245
- test
4346

44-
env:
45-
PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version || 'devel' }}
46-
4747
jobs:
4848
build-package-docs:
49-
runs-on: ubuntu-latest
50-
steps:
51-
- name: Checkout Ansible documentation
52-
uses: actions/checkout@v4
53-
with:
54-
repository: >-
55-
${{
56-
github.event.inputs.repository-owner || 'ansible'
57-
}}/${{
58-
github.event.inputs.repository-name || 'ansible-documentation'
59-
}}
60-
ref: ${{ github.event.inputs.repository-branch || 'devel' }}
61-
path: build-directory
62-
63-
- name: Setup nox
64-
uses: wntrblm/nox@2025.02.09
65-
66-
- name: Output Python info
67-
run: python --version --version && which python
68-
69-
- name: Graft ansible-core
70-
run: nox -s clone-core
71-
working-directory: build-directory
72-
73-
- name: Install project requirements
74-
run: >-
75-
python -m pip install
76-
-r tests/requirements.in
77-
-c tests/requirements.txt
78-
working-directory: build-directory
79-
80-
- name: Set the COLLECTION_LIST variable
81-
if: env.PACKAGE_VERSION != 'devel'
82-
run: >-
83-
echo COLLECTION_LIST="${PACKAGE_VERSION}"
84-
>> "${GITHUB_ENV}"
85-
86-
- name: Set the VERSION variable
87-
run: echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}"
88-
89-
- name: Build the Ansible community package docs
90-
run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}"
91-
working-directory: build-directory/docs/docsite
92-
93-
- name: Create a tarball with the build contents
94-
run: >-
95-
tar -czvf
96-
ansible-package-docs-html-"${PACKAGE_VERSION}"-"$(date '+%Y-%m-%d')"-${{
97-
github.run_id
98-
}}-${{
99-
github.run_number
100-
}}-${{
101-
github.run_attempt
102-
}}.tar.gz
103-
--directory=_build/html/ .
104-
working-directory: build-directory/docs/docsite
105-
106-
- name: Create a downloadable archive that contains the tarball
107-
uses: actions/upload-artifact@v4
108-
with:
109-
name: package-docs-build
110-
path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz
111-
retention-days: 7
49+
name: 📝 Build
50+
uses: ./.github/workflows/reusable-build-docs.yaml
51+
with:
52+
repository-owner: ${{ github.event.inputs.repository-owner }}
53+
repository-name: ${{ github.event.inputs.repository-name }}
54+
repository-branch: ${{ github.event.inputs.repository-branch }}
55+
ansible-package-version: ${{ github.event.inputs.ansible-package-version }}
56+
secrets:
57+
DOCS_BOT_TOKEN: ${{ secrets.DOCS_BOT_TOKEN }}
11258

113-
check-deploy:
59+
deploy-package-docs:
60+
name: 🚀 Deploy
11461
if: github.event_name == 'workflow_dispatch' && github.event.inputs.deploy == 'true'
11562
needs: build-package-docs
116-
runs-on: ubuntu-latest
117-
steps:
118-
- name: Log the workflow inputs if deployed
119-
run: |
120-
{
121-
echo "## Deployment details :shipit:";
122-
echo "Publish to: ${{ github.event.inputs.deployment-environment }}";
123-
echo "Package version: ${{ github.event.inputs.ansible-package-version }}";
124-
echo "Owner: ${{ github.event.inputs.repository-owner }}";
125-
echo "Branch: ${{ github.event.inputs.repository-branch }}";
126-
} >> "${GITHUB_STEP_SUMMARY}"
127-
128-
notify-build-failures:
129-
if: failure()
130-
needs: build-package-docs
131-
runs-on: ubuntu-latest
132-
env:
133-
ROOM_URL: https://ansible-accounts.ems.host/_matrix/client/v3/rooms/!HJtetIFWYEIDBOXxFE:libera.chat/send/m.room.message
134-
FAIL_MESSAGE: >-
135-
Oh no! A community package docs build has failed.
136-
Check this workflow run to see what went wrong:
137-
https://github.com/ansible/ansible-documentation/actions/runs/${{ github.run_id }}
138-
@orandon @samccann
139-
steps:
140-
- name: Set a transaction ID
141-
run: echo "TX_ID=$(date +%s)" >> "${GITHUB_ENV}"
142-
143-
- name: Notify the DaWGs in Matrix
144-
run: |
145-
curl -X PUT "${{ env.ROOM_URL }}/${TX_ID}" \
146-
-H "Authorization: Bearer ${{ secrets.DOCS_BOT_TOKEN }}" \
147-
-H "Content-Type: application/json" \
148-
-d '{"msgtype": "m.text", "body": "${{ env.FAIL_MESSAGE }}"}'
149-
150-
deploy-package-docs:
151-
needs:
152-
- check-deploy
153-
runs-on: ubuntu-latest
154-
environment:
155-
name: deploy-package-docs
156-
url: ${{ env.ENV_URL }}
157-
env:
158-
TARGET: ${{ github.event.inputs.deployment-environment }}
159-
DEST_REPO: ansible-community/package-doc-builds
160-
USER_EMAIL: "41898282+github-actions[bot]@users.noreply.github.com"
161-
USER_NAME: "github-actions[bot]"
162-
steps:
163-
- name: Download the build archive
164-
uses: actions/download-artifact@v4
165-
with:
166-
name: package-docs-build
167-
168-
- name: Extract the tarball
169-
run: >-
170-
tar -xvzf
171-
ansible-package-docs-html-*.tar.gz
172-
--one-top-level
173-
174-
- name: Set the production branch and url
175-
if: env.TARGET == 'production'
176-
env:
177-
BRANCH_NAME: ${{ github.event.inputs.ansible-package-version }}
178-
PROD_URL: https://ansible.readthedocs.io/projects/ansible
179-
run: |
180-
echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}"
181-
echo "ENV_URL=${PROD_URL}/${BRANCH_NAME}" >> "${GITHUB_ENV}"
182-
183-
- name: Set the test branch and url
184-
if: env.TARGET == 'test'
185-
env:
186-
TEST_URL: https://ansible-community.github.io/package-doc-builds
187-
run: |
188-
echo "BRANCH=gh-pages" >> "${GITHUB_ENV}"
189-
echo "ENV_URL=${TEST_URL}" >> "${GITHUB_ENV}"
190-
191-
- name: Checkout the deploy directory
192-
uses: actions/checkout@v4
193-
with:
194-
repository: ${{ env.DEST_REPO }}
195-
ref: ${{ env.BRANCH }}
196-
path: deploy-directory
197-
fetch-depth: 0
198-
ssh-key: ${{ secrets.DEPLOY_DOC_BUILD }}
199-
persist-credentials: true
200-
201-
- name: Copy the generated HTML and assets for production
202-
run: >-
203-
rsync -av --delete --mkpath
204-
ansible-package-docs-html-*/
205-
deploy-directory/docs
206-
207-
- name: Create a norobots.txt file for the test site
208-
if: env.TARGET == 'test'
209-
run: |
210-
touch norobots.txt
211-
echo "User-agent: *" > norobots.txt
212-
echo "Disallow: /" >> norobots.txt
213-
working-directory: deploy-directory/docs
214-
215-
- name: Configure the git user
216-
run: |
217-
git config --local user.email "${USER_EMAIL}"
218-
git config --local user.name "${USER_NAME}"
219-
working-directory: deploy-directory
220-
221-
- name: Git add the generated HTML and assets
222-
run: git add ./docs --all --force
223-
working-directory: deploy-directory
224-
225-
- name: Commit generated HTML and assets
226-
run: >-
227-
git diff-index --quiet HEAD ||
228-
git commit -m "Push docs build $(date '+%Y-%m-%d')-${{
229-
github.run_id
230-
}}-${{
231-
github.run_number
232-
}}-${{
233-
github.run_attempt
234-
}}"
235-
working-directory: deploy-directory
236-
237-
- name: Push build to deploy repository
238-
run: git push origin
239-
working-directory: deploy-directory
63+
uses: ./.github/workflows/reusable-deploy-docs.yaml
64+
with:
65+
ansible-package-version: ${{ github.event.inputs.ansible-package-version }}
66+
deployment-environment: ${{ github.event.inputs.deployment-environment }}
67+
repository-owner: ${{ github.event.inputs.repository-owner }}
68+
repository-branch: ${{ github.event.inputs.repository-branch }}
69+
secrets:
70+
DEPLOY_DOC_BUILD: ${{ secrets.DEPLOY_DOC_BUILD }}

‎.github/workflows/reusable-build-docs.yaml‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
name: Build docs
3+
4+
"on":
5+
workflow_call:
6+
inputs:
7+
repository-owner:
8+
description: GitHub account or org that owns the repository
9+
type: string
10+
required: false
11+
default: ansible
12+
repository-name:
13+
description: Name of the GitHub repository
14+
type: string
15+
required: false
16+
default: ansible-documentation
17+
repository-branch:
18+
description: Branch, tag, or commit SHA
19+
type: string
20+
required: false
21+
default: devel
22+
ansible-package-version:
23+
type: string
24+
description: Ansible community package version
25+
required: false
26+
default: devel
27+
secrets:
28+
DOCS_BOT_TOKEN:
29+
required: true
30+
31+
env:
32+
PACKAGE_VERSION: ${{ inputs.ansible-package-version }}
33+
34+
jobs:
35+
build-package-docs:
36+
runs-on: ubuntu-latest
37+
steps:
38+
- name: Checkout Ansible documentation
39+
uses: actions/checkout@v4
40+
with:
41+
repository: >-
42+
${{
43+
inputs.repository-owner
44+
}}/${{
45+
inputs.repository-name
46+
}}
47+
ref: ${{ inputs.repository-branch }}
48+
path: build-directory
49+
50+
- name: Setup nox
51+
uses: wntrblm/nox@2025.02.09
52+
53+
- name: Output Python info
54+
run: python --version --version && which python
55+
56+
- name: Graft ansible-core
57+
run: nox -s clone-core
58+
working-directory: build-directory
59+
60+
- name: Install project requirements
61+
run: >-
62+
python -m pip install
63+
-r tests/requirements.in
64+
-c tests/requirements.txt
65+
working-directory: build-directory
66+
67+
- name: Set the VERSION variable
68+
run: echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}"
69+
70+
- name: Build the Ansible community package docs
71+
run: >-
72+
make webdocs ANSIBLE_VERSION="${{
73+
env.PACKAGE_VERSION != 'devel' && env.PACKAGE_VERSION || ''
74+
}}"
75+
working-directory: build-directory/docs/docsite
76+
77+
- name: Create a tarball with the build contents
78+
run: >-
79+
tar -czvf
80+
ansible-package-docs-html-"${PACKAGE_VERSION}"-"$(date '+%Y-%m-%d')"-${{
81+
github.run_id
82+
}}-${{
83+
github.run_number
84+
}}-${{
85+
github.run_attempt
86+
}}.tar.gz
87+
--directory=_build/html/ .
88+
working-directory: build-directory/docs/docsite
89+
90+
- name: Create a downloadable archive that contains the tarball
91+
uses: actions/upload-artifact@v4
92+
with:
93+
name: package-docs-build
94+
path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz
95+
retention-days: 7
96+
97+
notify-build-failures:
98+
if: failure()
99+
needs: build-package-docs
100+
runs-on: ubuntu-latest
101+
env:
102+
ROOM_URL: https://ansible-accounts.ems.host/_matrix/client/v3/rooms/!HJtetIFWYEIDBOXxFE:libera.chat/send/m.room.message
103+
FAIL_MESSAGE: >-
104+
Oh no! A community package docs build has failed.
105+
Check this workflow run to see what went wrong:
106+
https://github.com/ansible/ansible-documentation/actions/runs/${{ github.run_id }}
107+
@orandon @samccann
108+
steps:
109+
- name: Set a transaction ID
110+
run: echo "TX_ID=$(date +%s)" >> "${GITHUB_ENV}"
111+
112+
- name: Notify the DaWGs in Matrix
113+
run: |
114+
curl -X PUT "${{ env.ROOM_URL }}/${TX_ID}" \
115+
-H "Authorization: Bearer ${{ secrets.DOCS_BOT_TOKEN }}" \
116+
-H "Content-Type: application/json" \
117+
-d '{"msgtype": "m.text", "body": "${{ env.FAIL_MESSAGE }}"}'

0 commit comments

Comments
 (0)