chore: merge .docker/sphinx-latex/Dockerfile into .devcontainer/Dockerfile

.devcontainer/Dockerfile

@@ -1,15 +1,22 @@
-FROM python:3.13 as final
+FROM python:3.13
+
+LABEL org.opencontainers.image.source="https://github.com/nextcloud/documentation"
+LABEL org.opencontainers.image.description="Sphinx build environment for Nextcloud documentation"
+LABEL org.opencontainers.image.licenses="AGPL-3.0"
 
 USER root
 
 # Add dev tools needed for building
 RUN export DEBIAN_FRONTEND=noninteractive \
     && apt-get update \
     && apt-get -y install --no-install-recommends \
-        curl gnupg2 git nano make graphviz imagemagick inkscape sass unzip wget php-cli npm latexmk texlive-latex-extra tex-gyre texlive-xetex \
-    && wget https://getcomposer.org/installer -qO /tmp/composer-setup.php \
-    && php /tmp/composer-setup.php \
-    && mv composer.phar /usr/local/bin/composer \
-    && npm install svgexport -g \
-    && rm -f /tmp/composer-setup.php \
+        ca-certificates curl gnupg2 git lsb-release nano make \
+        unzip wget \
+        latexmk texlive-fonts-extra texlive-fonts-extra-links texlive-fonts-recommended \
+        texlive-latex-extra texlive-latex-recommended tex-gyre texlive-xetex xindy \
+    && mktexlsr \
     && rm -rf /var/lib/apt/lists/*
+
+# Allow pip to install packages system-wide inside the container when running
+# as root (avoids PEP 668 "externally managed environment" error)
+RUN printf '[global]\nbreak-system-packages = true\n' > /etc/pip.conf

.github/dependabot.yml

@@ -18,7 +18,7 @@ updates:
     cooldown:
       default-days: 10
   - package-ecosystem: "docker"
-    directory: "/.docker/sphinx-latex"
+    directory: "/.devcontainer"
     schedule:
       interval: "weekly"
       time: "06:00"

.github/workflows/docker-build.yml

@@ -5,10 +5,10 @@ on:
     branches:
       - master
     paths:
-      - ".docker/sphinx-latex/**"
+      - ".devcontainer/**"
   pull_request:
     paths:
-      - ".docker/sphinx-latex/**"
+      - ".devcontainer/**"
   workflow_dispatch:
 
 permissions:
@@ -47,7 +47,7 @@ jobs:
       - name: Build and publish Docker image
         uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
-          context: .docker/sphinx-latex
+          context: .devcontainer
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

.github/workflows/sphinxbuild.yml

@@ -9,6 +9,7 @@ on:
 
 permissions:
   contents: read
+  packages: write
 
 concurrency:
   group: build-documentation-${{ github.head_ref || github.ref }}
@@ -76,20 +77,84 @@ jobs:
           name: ${{ matrix.manual.name }}
           path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
 
+  # ============================================================================
+  # PREPARE PDF IMAGE
+  # ============================================================================
+  # Detects whether .devcontainer/Dockerfile changed in this run.
+  # - If it changed: builds a fresh image, pushes it to GHCR with a SHA tag,
+  #   and outputs that tag so build-pdf uses the new image immediately.
+  # - If it did not change: outputs the stable ghcr.io/.../sphinx-latex:latest
+  #   tag so build-pdf uses the already-published image.
+  # ============================================================================
+  prepare-pdf-image:
+    name: Prepare PDF build image
+    runs-on: ubuntu-latest
+
+    outputs:
+      image: ${{ steps.result.outputs.image }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 2
+
+      - name: Check whether Dockerfile changed
+        id: changed
+        run: |
+          if git diff --name-only HEAD^ HEAD -- .devcontainer/Dockerfile 2>/dev/null | grep -q .; then
+            echo "dockerfile_changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "dockerfile_changed=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Set up Docker Buildx
+        if: steps.changed.outputs.dockerfile_changed == 'true'
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Login to GitHub Container Registry
+        if: steps.changed.outputs.dockerfile_changed == 'true'
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push image with SHA tag
+        if: steps.changed.outputs.dockerfile_changed == 'true'
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .devcontainer
+          push: true
+          tags: ghcr.io/${{ github.repository }}/sphinx-latex:sha-${{ github.sha }}
+          cache-from: type=registry,ref=ghcr.io/${{ github.repository }}/sphinx-latex:latest
+          cache-to: type=inline
+
+      - name: Output image reference
+        id: result
+        run: |
+          if [ "${{ steps.changed.outputs.dockerfile_changed }}" = "true" ]; then
+            echo "image=ghcr.io/${{ github.repository }}/sphinx-latex:sha-${{ github.sha }}" >> $GITHUB_OUTPUT
+          else
+            echo "image=ghcr.io/${{ github.repository }}/sphinx-latex:latest" >> $GITHUB_OUTPUT
+          fi
+
   # ============================================================================
   # BUILD PDF
   # ============================================================================
   # Builds the PDF documentation using the pre-built sphinx-latex Docker image.
   # The image already contains all LaTeX packages, so no apt install is needed.
-  # Starts immediately without waiting for any setup job.
+  # Uses the image prepared by the prepare-pdf-image job: either the stable
+  # ghcr.io/.../sphinx-latex:latest image or a freshly built SHA-tagged image
+  # if .devcontainer/Dockerfile changed in this run.
   # ============================================================================
   build-pdf:
     name: Building ${{ matrix.manual.name }} PDF
     runs-on: ubuntu-latest
-    # Use the pre-built sphinx-latex image which has all LaTeX packages pre-installed.
-    # The image is built from .docker/sphinx-latex/Dockerfile by the docker-build.yml workflow
-    # and published to GHCR. Using latest ensures we always use the current image for this repo.
-    container: ghcr.io/nextcloud/documentation/sphinx-latex:latest
+    needs: prepare-pdf-image
+    # Use the image prepared by prepare-pdf-image: either the stable ghcr image
+    # or a freshly built SHA-tagged image if .devcontainer/Dockerfile changed.
+    container: ${{ needs.prepare-pdf-image.outputs.image }}
 
     strategy:
       fail-fast: false

README.rst

@@ -123,9 +123,8 @@ Nightly Automated Build Steps
    2.  ``cd documentation``
    3.  ``git checkout <branch name>``
 2.  **Install**
-   1.  ``npm install svgexport -g --unsafe-perm=true``
-   2.  ``pip3 install -r requirements.txt``
-   3.  ``make all``
+   1.  ``pip3 install -r requirements.txt``
+   2.  ``make all``
 
 
 Building HTML
@@ -215,15 +214,5 @@ documentation, ``make html`` to build the HTML documentation or ``make pdf`` to
 ``make SPHINXBUILD=sphinx-autobuild html`` in combination with `port forwarding <https://code.visualstudio.com/docs/devcontainers/containers#_forwarding-or-publishing-a-port>`_
 to  watch file changes and automatically reload the html preview.
 
-Icons
------
-
-To compile and update the icons list in the designer manual, you will also need
-
-1. inkscape
-2. sass
-3. unzip
-4. wget
-
 .. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US
 .. _`Xcode command line tools`: https://stackoverflow.com/questions/9329243/xcode-install-command-line-tools