fix: cache only texlive-fonts-extra installed files, install other LaTeX packages normally

[Copilot]

The texlive-fonts-extra package is the primary bottleneck when installing LaTeX dependencies in CI, due to its large size (~500 MB of font data). This PR handles it separately via a manual copy/restore cache, while all other LaTeX packages are installed normally via apt-get install.

Changes Made

• setup-latex-cache job — now exclusively handles texlive-fonts-extra:

  1. Checks the installed-files cache (~/.cache/texlive-fonts-extra)
  2. On miss: installs texlive-fonts-extra via apt, then copies all its files (enumerated via dpkg -L) into the cache directory
  3. Saves the cache

• build job:

  • Restores the texlive-fonts-extra installed-files cache and copies files back via sudo cp -r ~/.cache/texlive-fonts-extra/. / (with apt fallback if cache is missing)
  • Installs all other LaTeX packages (texlive-fonts-recommended, latexmk, texlive-latex-extra, texlive-latex-recommended, texlive-xetex, texlive-fonts-extra-links, xindy, tex-gyre) normally via a plain apt-get install with retry logic
  • Removed all .deb apt-cache machinery (no more Configure apt cache, Download LaTeX packages, Restore LaTeX apt cache, Install LaTeX from cache steps)

☑️ Resolves

🖼️ Screenshots

N/A — CI workflow change only.

Original prompt

Problem

The Install LaTeX from cache step in .github/workflows/sphinxbuild.yml is too slow — it hits a 5-minute timeout because dpkg -i unpacking all texlive .deb files from the apt cache takes too long. The current approach caches .deb files but still re-runs dpkg on every job.

Solution

Replace the current .deb-based cache approach with a cached installed files approach:

1. After installing LaTeX via apt-get, copy the installed files to ~/.cache/latex-installed/ (a home-relative path safe for actions/cache)
2. On cache hit, restore those files by copying them back to their system destinations using sudo cp
3. This makes the actions/cache action work without permission issues (it only touches the home path), while a simple sudo cp handles the privileged restore

Implementation

Modify .github/workflows/sphinxbuild.yml:

In the setup-latex-cache job

Replace the current apt download-only + .deb cache approach with:

• Install LaTeX fully via apt-get install (not --download-only)
• Copy installed files to ~/.cache/latex-installed/ covering all relevant paths:
  • /usr/share/texlive → ~/.cache/latex-installed/texlive
  • /usr/share/texmf → ~/.cache/latex-installed/texmf
  • All relevant binaries from /usr/bin/ (latexmk, xelatex, pdflatex, lualatex, xindy, etc.) — use dpkg -L on each package to find the exact binaries
  • Any config files in /etc/texmf/ → ~/.cache/latex-installed/etc-texmf
  • Perl/lib files that texlive depends on (check dpkg -L output)
• chown -R $(id -u):$(id -g) the cache dir so actions/cache can save it
• Cache the ~/.cache/latex-installed/ path with actions/cache/save

In the build job

Replace the current "Restore LaTeX apt cache" + "Install LaTeX from cache" steps with:

• Restore ~/.cache/latex-installed/ via actions/cache/restore
• A single restore step that uses sudo cp -r to put everything back in system paths
• Handle binaries, shared data, config, and any symlinks correctly
• Make sure the restored install is fully functional for latexmk, xelatex, pdflatex, and xindy

Key requirements

• Use dpkg -L for all installed packages to get the complete, accurate file list — do not guess paths
• The cache key should reflect the package set and OS version (similar to current key format)
• The setup-latex-cache job should still use lookup-only on first check to skip re-running if cache already exists
• Restore must be fast — the whole point is to avoid the slow dpkg unpack on every build
• Remove the now-unnecessary timeout-minutes: 5 that was causing failures
• Remove the old .deb cache paths and related steps entirely

The cache size may be large (~1-2GB) — that's acceptable given the speed improvement.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Is it possible to have the workflow update the runner image by installing dependencies, and then use that image in the following jobs ? Because it seems even installing the packages takes too much time/cpu

Assistant: ## Short answer: Not natively — but there's a better approach

GitHub Actions jobs always start from a fresh runner image — you can't mutate a runner in one job and pass that modified state to the next. Each job is an isolated VM.

The right solution for your use case is a custom Docker image stored in GHCR with LaTeX pre-installed. This avoids the install overhead entirely since the packages are baked into the image layer.

---

The real problem

Looking at the failing job, the Install LaTeX from cache step is hitting a 5-minute timeout while running sudo dpkg -i --force-depends on all the texlive .deb files. That's a lot of large packages to unpack sequentially.

---

Recommended fix: Pre-built Docker image on GHCR

Create a Dockerfile and a separate workflow that builds + publishes it to GHCR. Then use it as the container in your build jobs.

1. Add a Dockerfile:

FROM ubuntu:24.04

RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    python3-pil python3-pip \
    texlive-fonts-recommended latexmk \
    texlive-latex-extra texlive-latex-recommended texlive-xetex \
    texlive-fonts-extra-links texlive-fonts-extra xindy tex-gyre \
    make git \
  && rm -rf /var/lib/apt/lists/*

2. Add a workflow to build & publish the image:

name: Build Sphinx+LaTeX image

on:
  push:
    paths:
      - '.docker/sphinx-latex/**'
    branches: [master]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: d...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

[skjnldsv]

@copilot, maybe we don't need to cache the other latex deps after all, since only the texlive-fonts-extra is the most problematic one. I think we can just install them normally on the build step. But we keep the manual install/restore of texlive-fonts-extra ?

[Copilot]

@copilot, maybe we don't need to cache the other latex deps after all, since only the texlive-fonts-extra is the most problematic one. I think we can just install them normally on the build step. But ...

Done in 0d1af66. Dropped the entire .deb apt-cache for the other packages — they're now just installed normally via apt-get install in the build step. The setup-latex-cache job is now exclusively for texlive-fonts-extra, and the build job restores its files via sudo cp -r before running the plain apt install for everything else.