From 7f6a4b4d1ea28da977775bbc3fc1b15542ee6a09 Mon Sep 17 00:00:00 2001 From: nextcloud-command Date: Thu, 2 Apr 2026 11:33:51 +0000 Subject: [PATCH 1/3] chore: update .github/workflows/sphinxbuild.yml from master branch Signed-off-by: GitHub --- .github/workflows/sphinxbuild.yml | 285 ++++++++++++++++++++++++++---- 1 file changed, 248 insertions(+), 37 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index 795da28ca39..2b5fc72d405 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -1,4 +1,4 @@ -name: "Pull Request Docs Check" +name: "Build documentation" on: pull_request: @@ -7,55 +7,266 @@ on: - master - stable* +permissions: + contents: read + jobs: - user_manual: + build: + + name: Build ${{ matrix.manual.name }} runs-on: ubuntu-latest + + strategy: + matrix: + manual: + - name: "user_manual" + directory: "user_manual" + make_target: "html" + build_path: "_build/html" + build_pdf_path: "_build/latex" + publish: true + + - name: "user_manual-en" + directory: "user_manual" + make_target: "html-lang-en" + build_path: "_build/html" + publish: false + + - name: "developer_manual" + directory: "developer_manual" + make_target: "html" + build_path: "_build/html/com" + publish: true + + - name: "admin_manual" + directory: "admin_manual" + make_target: "html" + build_path: "_build/html/com" + build_pdf_path: "_build/latex" + publish: true + steps: - - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 - - uses: actions/setup-python@7f4fc3e22c37d6ff65e88745f38bd3157c663f7c # v4 + - name: Cache git metadata + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 with: - python-version: '3.12' - cache: 'pip' - - name: Install pip dependencies - run: pip install -r requirements.txt - - name: Build using Makefile - run: cd user_manual && make html + path: .git + key: git-metadata-${{ github.sha }} + restore-keys: | + git-metadata-${{ github.sha }} + git-metadata - user_manual-en: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 - - uses: actions/setup-python@7f4fc3e22c37d6ff65e88745f38bd3157c663f7c # v4 + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Configure apt cache to use /dev/shm + if: ${{ matrix.manual.build_pdf_path }} + run: | + mkdir -p /dev/shm/apt/cache/archives + echo 'Dir::Cache::archives "/dev/shm/apt/cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-shm + + - name: Cache LaTeX apt packages + if: ${{ matrix.manual.build_pdf_path }} + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 with: - python-version: '3.12' - - name: Install pip dependencies - run: pip install -r requirements.txt - - name: Build using Makefile - run: cd user_manual && make html-lang-en + path: /dev/shm/apt/cache/archives + key: latex-apt-${{ runner.os }}-${{ hashFiles('.github/workflows/sphinxbuild.yml') }} + restore-keys: | + latex-apt-${{ runner.os }}- - developer_manual: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 - - uses: actions/setup-python@7f4fc3e22c37d6ff65e88745f38bd3157c663f7c # v4 + - name: Install LaTeX dependencies + if: ${{ matrix.manual.build_pdf_path }} + run: | + sudo DEBIAN_FRONTEND=noninteractive apt-get update + sudo 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 + + - name: Fix apt cache ownership for caching + if: ${{ matrix.manual.build_pdf_path }} + run: sudo chown -R $(id -u):$(id -g) /dev/shm/apt/cache/archives + + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 with: - python-version: '3.12' + python-version: '3.10' cache: 'pip' + - name: Install pip dependencies run: pip install -r requirements.txt - - name: Build using Makefile - run: cd developer_manual && make html - admin_manual: + - name: Build html documentation + run: cd ${{ matrix.manual.directory }} && make ${{ matrix.manual.make_target }} + + - name: Compute PDF release version + if: ${{ matrix.manual.build_pdf_path }} + id: pdf_version + run: | + branch="${GITHUB_REF#refs/heads/}" + if [[ "$branch" == stable* ]]; then + echo "release=${branch#stable}" >> $GITHUB_OUTPUT + else + echo "release=latest" >> $GITHUB_OUTPUT + fi + + - name: Build pdf documentation + if: ${{ matrix.manual.build_pdf_path }} + env: + DOCS_RELEASE: ${{ steps.pdf_version.outputs.release }} + run: | + set -e + cd ${{ matrix.manual.directory }} + make latexpdf + ls -la ${{ matrix.manual.build_pdf_path }} + cp ${{ matrix.manual.build_pdf_path }}/*.pdf ${{ matrix.manual.build_path }}/ + + - name: Upload static documentation + uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 + if: ${{ matrix.manual.publish }} + with: + name: ${{ matrix.manual.name }} + path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }} + + deploy: + name: Deploy pages + needs: build runs-on: ubuntu-latest + if: github.event_name == 'push' # Only deploy on push, not PR + + permissions: + contents: write + steps: - - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 - - uses: actions/setup-python@7f4fc3e22c37d6ff65e88745f38bd3157c663f7c # v4 + - name: Cache git metadata + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 with: - python-version: '3.12' - cache: 'pip' - - name: Install pip dependencies - run: pip install -r requirements.txt - - name: Build using Makefile - run: cd admin_manual && make html + path: .git + key: git-metadata-${{ github.sha }} + restore-keys: | + git-metadata-${{ github.sha }} + git-metadata + + - name: Checkout Github Pages branch + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: + ref: gh-pages + fetch-depth: 0 + token: ${{ secrets.COMMAND_BOT_PAT }} + + - name: Download all ${{ needs.build.outputs.branch_name }} artifacts + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + path: artifacts/ + + - name: Get branch name and find latest stable + id: branch + run: | + current_branch="${GITHUB_REF#refs/heads/}" + + # Find the highest numbered stable branch from the remote + highest_stable=$(git ls-remote --heads origin | sed -n 's?.*refs/heads/stable\([0-9]\{2\}\)$?\1?p' | sort -n | tail -1) + highest_stable_branch="stable${highest_stable}" + + echo "Current branch: $current_branch" + echo "Highest stable branch found: $highest_stable_branch" + + # Map actual branch names to deployment folder names + case "$current_branch" in + "master") + echo "branch_name=latest" >> $GITHUB_OUTPUT + ;; + "$highest_stable_branch") + echo "branch_name=stable" >> $GITHUB_OUTPUT + # Also record the numeric version so we can publish to server// too + echo "version_name=${highest_stable}" >> $GITHUB_OUTPUT + ;; + *) + # Remove stable prefix for current branch + current_branch="${current_branch#stable}" + echo "branch_name=$current_branch" >> $GITHUB_OUTPUT + ;; + esac + + echo "Deployment folder name: ${{ steps.branch.outputs.branch_name }}" + echo "Version name for additional deployment (if applicable): ${{ steps.branch.outputs.version_name }}" + + - name: Merge ${{ steps.branch.outputs.branch_name }} documentation artifacts into gh-pages + run: | + # List artifacts + ls -la artifacts/*/ + + # Cleanup old documentation + rm -rf ${{ steps.branch.outputs.branch_name }} + rm -rf server/${{ steps.branch.outputs.branch_name }} + mkdir -p server/${{ steps.branch.outputs.branch_name }} + + # Copy all built documentation into dedicated subdirectories + for artifact in artifacts/*; do + if [ -d "$artifact" ]; then + manual_name="$(basename "$artifact")" + mkdir -p "server/${{ steps.branch.outputs.branch_name }}/$manual_name" + cp -r "$artifact/"* "server/${{ steps.branch.outputs.branch_name }}/$manual_name/" + fi + done + + # Move pdf files to the root of the branch_name + mv server/${{ steps.branch.outputs.branch_name }}/*/*.pdf server/${{ steps.branch.outputs.branch_name }}/ || true + + # If this is the highest stable branch, also deploy to its versioned folder + if [ -n "${{ steps.branch.outputs.version_name }}" ]; then + rm -rf server/${{ steps.branch.outputs.version_name }} + cp -r server/${{ steps.branch.outputs.branch_name }} server/${{ steps.branch.outputs.version_name }} + fi + + # Cleanup + find . -type d -empty -delete + rm -rf artifacts + + - name: Add various redirects for go.php and user_manual english version + run: | + # Fetch source branches so git checkout origin/... works from the gh-pages checkout + git fetch origin ${{ github.event.repository.default_branch }} ${{ github.ref_name }} + + # Generate go.php redirect from main branch + git checkout origin/${{ github.event.repository.default_branch }} -- go.php/index.html + mkdir -p server/${{ steps.branch.outputs.branch_name }}/go.php + mv go.php/index.html server/${{ steps.branch.outputs.branch_name }}/go.php/index.html + + # Generate user_manual english redirect + git checkout origin/${{ github.ref_name }} -- user_manual/index.html + mkdir -p server/${{ steps.branch.outputs.branch_name }}/user_manual + mv user_manual/index.html server/${{ steps.branch.outputs.branch_name }}/user_manual/index.html + + - name: Commit ${{ steps.branch.outputs.branch_name }} documentation and push to gh-pages + run: | + git config --local user.email "nextcloud-command@users.noreply.github.com" + git config --local user.name "nextcloud-command" + git add . + git diff --staged --quiet || git commit -m "chore: deploy documentation for ${{ steps.branch.outputs.branch_name }}" + # Ensure we are up to date with the remote gh-pages branch + git pull --rebase origin gh-pages || true + git push origin gh-pages || echo "Nothing to push (expected if no changes)" + env: + GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }} + + summary: + needs: build + runs-on: ubuntu-latest + if: always() + + permissions: + contents: read + + name: build-deploy-summary + + steps: + # Only check if the build was successful + - name: Summary status + run: if ${{ needs.build.result != 'success' }}; then exit 1; fi From 2ff66bcd28e9ca4a193a45fe0bc0bc022e6fff6c Mon Sep 17 00:00:00 2001 From: nextcloud-command Date: Thu, 2 Apr 2026 12:09:44 +0000 Subject: [PATCH 2/3] chore: update user_manual/index.html from master branch Signed-off-by: GitHub --- user_manual/index.html | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 user_manual/index.html diff --git a/user_manual/index.html b/user_manual/index.html new file mode 100644 index 00000000000..85716245fb4 --- /dev/null +++ b/user_manual/index.html @@ -0,0 +1,11 @@ + + + + + Nextcloud Documentation + + + + + + From e207717f77b47d18907cfffeff9b6477e62c807c Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 2 Apr 2026 14:34:04 +0200 Subject: [PATCH 3/3] fix: missing `tex-gyre` dependency Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index 2b5fc72d405..06632239977 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -81,6 +81,7 @@ jobs: --no-install-recommends \ python3-pil \ python3-pip \ + tex-gyre \ texlive-fonts-recommended \ latexmk \ texlive-latex-extra \