Skip to content

Commit a4519b3

Browse files
Copilotskjnldsv
Copilot
and
skjnldsv
committed
ci: use Docker image for PDF builds, split HTML and PDF jobs
- Remove setup-latex-cache job: no longer needed as LaTeX packages are baked into the pre-built Docker image - Add build-html job: runs on ubuntu-latest with no LaTeX dependency, starts immediately without waiting for any setup - Add build-pdf job: uses ghcr.io/nextcloud/documentation/sphinx-latex:latest container, which already has all LaTeX packages pre-installed, so no apt install overhead at all - Update Dockerfile: add git (required by checkout action inside containers) and PIP_BREAK_SYSTEM_PACKAGES=1 (allows pip install on Ubuntu 24.04) - Update stage-and-check needs to [build-html, build-pdf] - Update summary needs and success conditions - Remove redundant git-metadata cache steps Agent-Logs-Url: https://github.com/nextcloud/documentation/sessions/035e13fc-b3f3-4251-b06b-79d24dfd3a8b Co-authored-by: skjnldsv <14975046+skjnldsv@users.noreply.github.com>
1 parent 66b6997 commit a4519b3

3 files changed

Lines changed: 71 additions & 151 deletions

File tree

‎.docker/sphinx-latex/Dockerfile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,6 @@ RUN apt-get update \
2525
&& mktexlsr \
2626
&& rm -rf /var/lib/apt/lists/*
2727

28-
# Allow pip to install packages system-wide inside the container (used by
29-
# actions/setup-python and plain pip invocations running as root)
28+
# Allow pip to install packages system-wide inside the container when running
29+
# as root (avoids PEP 668 "externally managed environment" error)
3030
RUN printf '[global]\nbreak-system-packages = true\n' > /etc/pip.conf

‎.github/workflows/docker-build.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ permissions:
1616
packages: write
1717

1818
jobs:
19-
build-and-push:
20-
name: Build and push sphinx-latex image
19+
build-and-publish:
20+
name: Build and publish sphinx-latex Docker image
2121
runs-on: ubuntu-latest
2222

2323
steps:
@@ -44,7 +44,7 @@ jobs:
4444
type=raw,value=latest,enable={{is_default_branch}}
4545
type=sha,prefix=sha-
4646
47-
- name: Build and push Docker image
47+
- name: Build and publish Docker image
4848
uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
4949
with:
5050
context: .docker/sphinx-latex

‎.github/workflows/sphinxbuild.yml‎

Lines changed: 66 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -15,62 +15,15 @@ concurrency:
1515
cancel-in-progress: true
1616

1717
jobs:
18-
setup-latex-cache:
19-
name: Cache LaTeX packages
20-
runs-on: ubuntu-latest
21-
22-
steps:
23-
- name: Configure apt cache
24-
run: |
25-
mkdir -p ${{ runner.temp }}/.cache/archives
26-
mkdir -p ${{ runner.temp }}/.cache/lists
27-
echo 'Dir::Cache::archives "${{ runner.temp }}/.cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-tmp
28-
29-
- name: Cache LaTeX apt packages
30-
id: cache-latex-apt
31-
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
32-
with:
33-
path: |
34-
${{ runner.temp }}/.cache/archives
35-
${{ runner.temp }}/.cache/lists
36-
key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023-v2
37-
restore-keys: |
38-
latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-
39-
latex-apt-${{ runner.os }}-${{ runner.arch }}-
40-
lookup-only: true
41-
42-
- name: Download LaTeX packages (cache miss only)
43-
if: steps.cache-latex-apt.outputs.cache-hit != 'true'
44-
run: |
45-
for i in 1 2 3; do
46-
sudo DEBIAN_FRONTEND=noninteractive apt-get update \
47-
-o Dir::State::lists="${{ runner.temp }}/.cache/lists" \
48-
-o Acquire::Retries=3 && break
49-
echo "apt-get update failed (attempt $i), retrying in 15s..."
50-
sleep 15
51-
done
52-
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
53-
--download-only \
54-
-o Dir::State::lists="${{ runner.temp }}/.cache/lists" \
55-
python3-pil python3-pip texlive-fonts-recommended latexmk \
56-
texlive-latex-extra texlive-latex-recommended texlive-xetex \
57-
texlive-fonts-extra-links texlive-fonts-extra xindy tex-gyre
58-
# Ensure downloaded packages are owned by the current user so they can be cached
59-
sudo chown -R $(id -u):$(id -g) ${{ runner.temp }}/.cache/
60-
61-
- name: Save LaTeX apt cache (cache miss only)
62-
if: steps.cache-latex-apt.outputs.cache-hit != 'true'
63-
uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
64-
with:
65-
path: |
66-
${{ runner.temp }}/.cache/archives
67-
${{ runner.temp }}/.cache/lists
68-
key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023-v2
69-
70-
build:
71-
name: Build ${{ matrix.manual.name }}
18+
# ============================================================================
19+
# BUILD HTML
20+
# ============================================================================
21+
# Builds the HTML documentation for all manuals. No LaTeX required.
22+
# Starts immediately without waiting for any setup job.
23+
# ============================================================================
24+
build-html:
25+
name: Building ${{ matrix.manual.name }} HTML
7226
runs-on: ubuntu-latest
73-
needs: setup-latex-cache
7427

7528
strategy:
7629
fail-fast: false
@@ -80,7 +33,6 @@ jobs:
8033
directory: "user_manual"
8134
make_target: "html"
8235
build_path: "_build/html"
83-
build_pdf_path: "_build/latex"
8436
publish: true
8537

8638
- name: "user_manual-en"
@@ -99,68 +51,73 @@ jobs:
9951
directory: "admin_manual"
10052
make_target: "html"
10153
build_path: "_build/html/com"
102-
build_pdf_path: "_build/latex"
10354
publish: true
10455

10556
steps:
106-
- name: Cache git metadata
107-
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
108-
with:
109-
path: .git
110-
key: git-metadata-${{ github.sha }}
111-
restore-keys: |
112-
git-metadata-${{ github.sha }}
113-
git-metadata
114-
11557
- name: Checkout repository
11658
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
11759

118-
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
60+
- name: Set up Python
61+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
11962
with:
12063
python-version: "3.13"
12164
cache: "pip"
12265

12366
- name: Install pip dependencies
124-
run: pip install -r requirements.txt
67+
run: python -m pip install -r requirements.txt
12568

126-
- name: Configure apt cache
127-
if: ${{ matrix.manual.build_pdf_path }}
128-
run: |
129-
mkdir -p ${{ runner.temp }}/.cache/archives
130-
mkdir -p ${{ runner.temp }}/.cache/lists
131-
echo 'Dir::Cache::archives "${{ runner.temp }}/.cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-tmp
69+
- name: Build html documentation
70+
run: cd ${{ matrix.manual.directory }} && make ${{ matrix.manual.make_target }}
13271

133-
- name: Restore LaTeX apt cache
134-
if: ${{ matrix.manual.build_pdf_path }}
135-
uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
72+
- name: Upload static documentation
73+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
74+
if: ${{ matrix.manual.publish }}
13675
with:
137-
# Use relative path https://github.com/actions/cache/issues/1127
138-
path: |
139-
${{ runner.temp }}/.cache/archives
140-
${{ runner.temp }}/.cache/lists
141-
key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023-v2
142-
restore-keys: |
143-
latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-
144-
latex-apt-${{ runner.os }}-${{ runner.arch }}-
145-
146-
- name: Install LaTeX from cache
147-
if: ${{ matrix.manual.build_pdf_path }}
148-
timeout-minutes: 5
149-
run: |
150-
debs=(${{ runner.temp }}/.cache/archives/*.deb)
151-
if [ ! -e "${debs[0]}" ]; then
152-
echo "No .deb files found in cache archives — cache may be empty or missing." >&2
153-
exit 1
154-
fi
155-
sudo dpkg -i --force-depends "${debs[@]}"
156-
sudo DEBIAN_FRONTEND=noninteractive apt-get install -f -y --no-install-recommends \
157-
-o Dir::State::lists="${{ runner.temp }}/.cache/lists"
76+
name: ${{ matrix.manual.name }}
77+
path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
15878

159-
- name: Build html documentation
160-
run: cd ${{ matrix.manual.directory }} && make ${{ matrix.manual.make_target }}
79+
# ============================================================================
80+
# BUILD PDF
81+
# ============================================================================
82+
# Builds the PDF documentation using the pre-built sphinx-latex Docker image.
83+
# The image already contains all LaTeX packages, so no apt install is needed.
84+
# Starts immediately without waiting for any setup job.
85+
# ============================================================================
86+
build-pdf:
87+
name: Building ${{ matrix.manual.name }} PDF
88+
runs-on: ubuntu-latest
89+
# Use the pre-built sphinx-latex image which has all LaTeX packages pre-installed.
90+
# The image is built from .docker/sphinx-latex/Dockerfile by the docker-build.yml workflow
91+
# and published to GHCR. Using latest ensures we always use the current image for this repo.
92+
container: ghcr.io/nextcloud/documentation/sphinx-latex:latest
93+
94+
strategy:
95+
fail-fast: false
96+
matrix:
97+
manual:
98+
- name: "user_manual"
99+
directory: "user_manual"
100+
build_pdf_path: "_build/latex/Nextcloud_User_Manual.pdf"
101+
102+
- name: "admin_manual"
103+
directory: "admin_manual"
104+
build_pdf_path: "_build/latex/Nextcloud_Server_Administration_Manual.pdf"
105+
106+
steps:
107+
- name: Checkout repository
108+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
109+
110+
- name: Set up Python
111+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
112+
with:
113+
python-version: "3.13"
114+
# pip cache is not compatible with the Docker container
115+
# cache: "pip"
116+
117+
- name: Install pip dependencies
118+
run: python -m pip install -r requirements.txt
161119

162120
- name: Compute PDF release version
163-
if: ${{ matrix.manual.build_pdf_path }}
164121
id: pdf_version
165122
run: |
166123
branch="${GITHUB_REF#refs/heads/}"
@@ -171,22 +128,19 @@ jobs:
171128
fi
172129
173130
- name: Build pdf documentation
174-
if: ${{ matrix.manual.build_pdf_path }}
175131
env:
176132
DOCS_RELEASE: ${{ steps.pdf_version.outputs.release }}
177133
run: |
178134
set -e
179135
cd ${{ matrix.manual.directory }}
180136
make latexpdf
181137
ls -la ${{ matrix.manual.build_pdf_path }}
182-
cp ${{ matrix.manual.build_pdf_path }}/*.pdf ${{ matrix.manual.build_path }}/
183138
184-
- name: Upload static documentation
139+
- name: Upload PDF documentation
185140
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
186-
if: ${{ matrix.manual.publish }}
187141
with:
188-
name: ${{ matrix.manual.name }}
189-
path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
142+
name: ${{ matrix.manual.name }}-pdf
143+
path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_pdf_path }}
190144

191145
# ============================================================================
192146
# STAGE AND VALIDATE
@@ -203,7 +157,7 @@ jobs:
203157
# ============================================================================
204158
stage-and-check:
205159
name: Stage and check documentation
206-
needs: build
160+
needs: [build-html, build-pdf]
207161
runs-on: ubuntu-latest
208162

209163
outputs:
@@ -223,15 +177,6 @@ jobs:
223177
additional_deployment: ${{ steps.branch.outputs.additional_deployment }}
224178

225179
steps:
226-
- name: Cache git metadata
227-
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
228-
with:
229-
path: .git
230-
key: git-metadata-${{ github.sha }}
231-
restore-keys: |
232-
git-metadata-${{ github.sha }}
233-
git-metadata
234-
235180
- name: Checkout repository
236181
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
237182

@@ -249,22 +194,6 @@ jobs:
249194
# 2. Merge in the new artifacts (what we're about to deploy)
250195
# 3. Run link checks only on the NEW content, but with full context
251196
# ========================================================================
252-
# ========================================================================
253-
# FETCH GH-PAGES FOR LINK VALIDATION CONTEXT
254-
# ========================================================================
255-
# We need the existing gh-pages content (old versions) so that link
256-
# validation can resolve cross-version references. We use git cache
257-
# to make this fast.
258-
# ========================================================================
259-
- name: Cache git metadata for gh-pages
260-
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
261-
with:
262-
path: .git
263-
key: git-metadata-${{ github.sha }}
264-
restore-keys: |
265-
git-metadata-${{ github.sha }}
266-
git-metadata
267-
268197
- name: Checkout gh-pages branch for validation context
269198
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
270199
with:
@@ -402,15 +331,6 @@ jobs:
402331
pull-requests: write
403332

404333
steps:
405-
- name: Cache git metadata
406-
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
407-
with:
408-
path: .git
409-
key: git-metadata-${{ github.sha }}
410-
restore-keys: |
411-
git-metadata-${{ github.sha }}
412-
git-metadata
413-
414334
- name: Checkout gh-pages branch
415335
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
416336
with:
@@ -526,7 +446,7 @@ jobs:
526446
GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }}
527447

528448
summary:
529-
needs: [build, stage-and-check, deploy]
449+
needs: [build-html, build-pdf, stage-and-check, deploy]
530450
runs-on: ubuntu-latest-low
531451
if: always()
532452

@@ -540,10 +460,10 @@ jobs:
540460
run: |
541461
if ${{ github.event_name == 'pull_request' }}
542462
then
543-
echo "This workflow ran for a pull request. We need build and stage-and-check to succeed, but deploy will be skipped"
544-
if ${{ needs.build.result != 'success' || needs.stage-and-check.result != 'success' || needs.deploy.result != 'skipped' }}; then exit 1; fi
463+
echo "This workflow ran for a pull request. We need build-html, build-pdf and stage-and-check to succeed, but deploy will be skipped"
464+
if ${{ needs.build-html.result != 'success' || needs.build-pdf.result != 'success' || needs.stage-and-check.result != 'success' || needs.deploy.result != 'skipped' }}; then exit 1; fi
545465
else
546466
echo "This workflow ran for a push. We need all jobs to succeed, including deploy"
547-
if ${{ needs.build.result != 'success' || needs.stage-and-check.result != 'success' || needs.deploy.result != 'success' }}; then exit 1; fi
467+
if ${{ needs.build-html.result != 'success' || needs.build-pdf.result != 'success' || needs.stage-and-check.result != 'success' || needs.deploy.result != 'success' }}; then exit 1; fi
548468
fi
549469

0 commit comments

Comments
 (0)