From 66958c9176918d784d65095b81875d4a27194775 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 8 Apr 2026 13:49:04 +0200 Subject: [PATCH 1/9] perf(ci): add build cancel concurrency Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index e85645e4ffd..a7d876d4746 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -10,6 +10,10 @@ on: permissions: contents: read +concurrency: + group: build-documentation-${{ github.head_ref || github.run_id }} + cancel-in-progress: true + jobs: build: From 845927c633eca93312ccc66ab65202037f9eaa37 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 8 Apr 2026 13:50:05 +0200 Subject: [PATCH 2/9] fix(ci): deploy pages via pull request with auto-merge Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index a7d876d4746..ab206ed8dcc 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -248,15 +248,25 @@ jobs: 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)" + - name: Create Pull Request for documentation deployment + uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0 + id: cpr + with: + token: ${{ secrets.COMMAND_BOT_PAT }} + commit-message: "chore: deploy documentation for ${{ steps.branch.outputs.branch_name }}" + committer: nextcloud-command + author: nextcloud-command + signoff: true + branch: "automated/deploy/documentation-${{ steps.branch.outputs.branch_name }}" + base: gh-pages + title: "Deploy documentation for ${{ steps.branch.outputs.branch_name }}" + body: "Automated documentation deployment from branch ${{ github.ref_name }}" + delete-branch: true + labels: "automated, 3. to review" + + - name: Enable Pull Request Automerge + run: gh pr merge --merge --auto "${{ steps.cpr.outputs.pull-request-number }}" + if: steps.cpr.outputs.pull-request-number != '' env: GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }} From 725c55e7c7de3c249b5f11b2e740ad210a9ee955 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 8 Apr 2026 13:13:26 +0200 Subject: [PATCH 3/9] perf(ci): improve LaTeX caching with dedicated setup job Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 90 +++++++++++++++++++------------ 1 file changed, 57 insertions(+), 33 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index ab206ed8dcc..6c2da88f9df 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -15,10 +15,43 @@ concurrency: cancel-in-progress: true jobs: + setup-latex-cache: + name: Cache LaTeX packages + runs-on: ubuntu-latest + + steps: + - name: Configure apt cache + run: | + mkdir -p ${{ runner.temp }}/.cache/archives + echo 'Dir::Cache::archives "${{ runner.temp }}/.cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-tmp + + - name: Cache LaTeX apt packages + id: cache-latex-apt + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 + with: + path: ${{ runner.temp }}/.cache/archives + key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023 + restore-keys: | + latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04- + latex-apt-${{ runner.os }}-${{ runner.arch }}- + + - name: Download LaTeX packages (cache miss only) + if: steps.cache-latex-apt.outputs.cache-hit != 'true' + run: | + sudo DEBIAN_FRONTEND=noninteractive apt-get update + sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + --download-only \ + python3-pil python3-pip texlive-fonts-recommended latexmk \ + texlive-latex-extra texlive-latex-recommended texlive-xetex \ + texlive-fonts-extra-links texlive-fonts-extra xindy + # Ensure downloaded packages are owned by the current user so they can be cached + sudo chown -R $(id -u):$(id -g) ${{ runner.temp }}/.cache/archives + build: name: Build ${{ matrix.manual.name }} runs-on: ubuntu-latest + needs: setup-latex-cache strategy: matrix: @@ -62,49 +95,40 @@ jobs: - name: Checkout repository uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Configure apt cache to use /dev/shm + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 + with: + python-version: '3.12' + cache: 'pip' + + - name: Install pip dependencies + run: pip install -r requirements.txt + + - name: Configure apt cache 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 + mkdir -p ${{ runner.temp }}/.cache/archives + echo 'Dir::Cache::archives "${{ runner.temp }}/.cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-tmp - - name: Cache LaTeX apt packages + - name: Restore LaTeX apt cache if: ${{ matrix.manual.build_pdf_path }} - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 + uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 with: - path: /dev/shm/apt/cache/archives - key: latex-apt-${{ runner.os }}-${{ hashFiles('.github/workflows/sphinxbuild.yml') }} + # Use relative path https://github.com/actions/cache/issues/1127 + path: ${{ runner.temp }}/.cache/archives + key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023 restore-keys: | - latex-apt-${{ runner.os }}- + latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04- + latex-apt-${{ runner.os }}-${{ runner.arch }}- - - name: Install LaTeX dependencies + - name: Install LaTeX from cache 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' - cache: 'pip' - - - name: Install pip dependencies - run: pip install -r requirements.txt + sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + --no-download \ + 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: Build html documentation run: cd ${{ matrix.manual.directory }} && make ${{ matrix.manual.make_target }} From 332518e643993eb2e5e1954497f04becd81e8dca Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 8 Apr 2026 13:51:44 +0200 Subject: [PATCH 4/9] feat(ci): add lychee broken link checker and stage-and-check job Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 597 ++++++++++++++++++++---------- 1 file changed, 392 insertions(+), 205 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index 6c2da88f9df..d314cf3c201 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -48,7 +48,6 @@ jobs: sudo chown -R $(id -u):$(id -g) ${{ runner.temp }}/.cache/archives build: - name: Build ${{ matrix.manual.name }} runs-on: ubuntu-latest needs: setup-latex-cache @@ -83,219 +82,408 @@ jobs: publish: true steps: - - name: Cache git metadata - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 - with: - path: .git - key: git-metadata-${{ github.sha }} - restore-keys: | - git-metadata-${{ github.sha }} - git-metadata - - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 - with: - python-version: '3.12' - cache: 'pip' - - - name: Install pip dependencies - run: pip install -r requirements.txt - - - name: Configure apt cache - if: ${{ matrix.manual.build_pdf_path }} - run: | - mkdir -p ${{ runner.temp }}/.cache/archives - echo 'Dir::Cache::archives "${{ runner.temp }}/.cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-tmp - - - name: Restore LaTeX apt cache - if: ${{ matrix.manual.build_pdf_path }} - uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 - with: - # Use relative path https://github.com/actions/cache/issues/1127 - path: ${{ runner.temp }}/.cache/archives - key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023 - restore-keys: | - latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04- - latex-apt-${{ runner.os }}-${{ runner.arch }}- - - - name: Install LaTeX from cache - 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 \ - --no-download \ - 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: 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 }} + - name: Cache git metadata + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 + with: + path: .git + key: git-metadata-${{ github.sha }} + restore-keys: | + git-metadata-${{ github.sha }} + git-metadata - deploy: - name: Deploy pages + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 + with: + python-version: "3.12" + cache: "pip" + + - name: Install pip dependencies + run: pip install -r requirements.txt + + - name: Configure apt cache + if: ${{ matrix.manual.build_pdf_path }} + run: | + mkdir -p ${{ runner.temp }}/.cache/archives + echo 'Dir::Cache::archives "${{ runner.temp }}/.cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-tmp + + - name: Restore LaTeX apt cache + if: ${{ matrix.manual.build_pdf_path }} + uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 + with: + # Use relative path https://github.com/actions/cache/issues/1127 + path: ${{ runner.temp }}/.cache/archives + key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023 + restore-keys: | + latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04- + latex-apt-${{ runner.os }}-${{ runner.arch }}- + + - name: Install LaTeX from cache + 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 \ + --no-download \ + 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: 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 }} + + # ============================================================================ + # STAGE AND VALIDATE + # ============================================================================ + # This job is responsible for: + # 1. Determining deployment target folder names (branch_name/version_name) + # 2. Organizing build artifacts into a clean structure + # 3. Validating the documentation (link checking) + # 4. Uploading a minimal staging artifact for the deploy job + # + # IMPORTANT: This job does NOT modify gh-pages. It only prepares and validates + # the artifacts that will be deployed. The actual deployment happens in the + # deploy job. + # ============================================================================ + stage-and-check: + name: Stage and check documentation needs: build runs-on: ubuntu-latest - if: github.event_name == 'push' # Only deploy on push, not PR + + outputs: + # branch_name: The primary deployment folder name for this branch + # - master → "latest" + # - stable (if highest) → "stable" + # - stable (if not highest) → "" (numeric version) + branch_name: ${{ steps.branch.outputs.branch_name }} + + # additional_deployment: ONLY set if deploying the highest stable branch + # - If this IS the highest stable → "" (numeric version, e.g. "32") + # - Otherwise → "" (empty string) + # + # This allows the highest stable to be deployed to TWO locations: + # server/stable/ (via branch_name) + # server// (via additional_deployment) + additional_deployment: ${{ steps.branch.outputs.additional_deployment }} + + steps: + - name: Cache git metadata + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 + with: + path: .git + key: git-metadata-${{ github.sha }} + restore-keys: | + git-metadata-${{ github.sha }} + git-metadata + + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Download all artifacts + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + path: artifacts/ + + # ======================================================================== + # PREPARE FOR LINK VALIDATION: BUILD FULL PAGE CONTEXT + # ======================================================================== + # We need to validate links in the new documentation, but some links may + # point to other versions or branches that are already deployed. So we: + # 1. Fetch the existing gh-pages content (old versions) + # 2. Merge in the new artifacts (what we're about to deploy) + # 3. Run link checks only on the NEW content, but with full context + # ======================================================================== + # ======================================================================== + # FETCH GH-PAGES FOR LINK VALIDATION CONTEXT + # ======================================================================== + # We need the existing gh-pages content (old versions) so that link + # validation can resolve cross-version references. We use git cache + # to make this fast. + # ======================================================================== + - name: Cache git metadata for gh-pages + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 + with: + path: .git + key: git-metadata-${{ github.sha }} + restore-keys: | + git-metadata-${{ github.sha }} + git-metadata + + - name: Checkout gh-pages branch for validation context + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + ref: gh-pages + fetch-depth: 0 + path: validation-context + + # ======================================================================== + # DETERMINE DEPLOYMENT TARGETS (branch_name and version_name) + # ======================================================================== + # Logic: + # 1. Determine current_branch: use GITHUB_REF if push, GITHUB_BASE_REF if PR + # 2. Find the highest numbered stable branch from git remotes + # 3. Map the current branch to deployment folder names: + # + # master → branch_name=latest (no version_name) + # + # stable where N is highest → branch_name=stable, version_name= + # (deployed to both server/stable/ and server//) + # + # stable where N is not highest → branch_name= (no version_name) + # (deployed only to server//) + # + # Any other branch → branch_name= (no version_name) + # ======================================================================== + - name: Determine deployment targets (branch_name and version_name) + id: branch + run: | + # Determine which branch we're building from + current_branch=${GITHUB_REF#refs/heads/} + if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then + current_branch=${GITHUB_BASE_REF} + fi + + # Find the highest numbered stable branch from the remote + # e.g., "stable30", "stable31", "stable32" → extract "32" + 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 branch to deployment folder names + case "$current_branch" in + "master") + # master always deploys to "latest" + echo "branch_name=latest" >> $GITHUB_OUTPUT + ;; + "$highest_stable_branch") + # Highest stable gets TWO locations: both "stable" and "" + echo "branch_name=stable" >> $GITHUB_OUTPUT + echo "additional_deployment=${highest_stable}" >> $GITHUB_OUTPUT + ;; + *) + # Other branches (including older stable branches) get their branch name + # For stable where N is not highest: strip "stable" prefix to get just "" + branch_for_deploy="${current_branch#stable}" + echo "branch_name=$branch_for_deploy" >> $GITHUB_OUTPUT + ;; + esac + + - name: Log deployment targets + run: | + echo "Deployment target folder: ${{ steps.branch.outputs.branch_name }}" + echo "Additional deployment folder (if applicable): ${{ steps.branch.outputs.additional_deployment }}" + + # ======================================================================== + # BUILD FULL DEPLOYMENT STRUCTURE + # ======================================================================== + # Build the complete gh-pages structure in deploy-staging/ so that: + # 1. Lychee can validate the new content in its actual deployment context + # 2. The staged site includes existing versions (for cross-version link validation) + # 3. The staged site is ready to be copied directly to gh-pages + # ======================================================================== + - name: Build full deployment structure + run: | + branch="${{ steps.branch.outputs.branch_name }}" + additional="${{ steps.branch.outputs.additional_deployment }}" + + # Start with existing gh-pages content (all current versions) + mkdir -p deploy-staging/server + cp -r validation-context/server/* deploy-staging/server/ || true + + # Organize new artifacts into the deployment structure + mkdir -p "deploy-staging/${branch}" + + for artifact in artifacts/*; do + if [ -d "$artifact" ]; then + manual_name="$(basename "$artifact")" + mkdir -p "deploy-staging/${branch}/$manual_name" + cp -r "$artifact/"* "deploy-staging/${branch}/$manual_name/" + fi + done + + # Move PDF files to the root of the branch folder + mv "deploy-staging/${branch}"/*/*.pdf "deploy-staging/${branch}/" || true + + # If this is the highest stable, also prepare the additional deployment folder + if [ -n "${additional}" ]; then + mkdir -p "deploy-staging/${additional}" + cp -r "deploy-staging/${branch}"/* "deploy-staging/${additional}/" + fi + + # Clean up empty directories + find deploy-staging -type d -empty -delete + + echo "Full deployment structure prepared:" + find deploy-staging -type d -maxdepth 2 + + # ======================================================================== + # UPLOAD STAGING ARTIFACTS + # ======================================================================== + # Upload only the minimal, organized artifacts needed for deployment. + # The deploy job will download this and place it in the correct location + # on the gh-pages branch. + # ======================================================================== + - name: Upload staged artifacts + uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 + with: + name: staged-site + path: deploy-staging/ + + # ======================================================================== + # VALIDATION: CHECK FOR BROKEN LINKS (NEW CONTENT IN FULL CONTEXT) + # ======================================================================== + # Run link checker against the new documentation at deploy-staging//. + # The deploy-staging/ directory includes all existing versions (from + # validation-context/), so lychee can validate cross-version links like + # references to stable/, other version numbers, etc. + # ======================================================================== + - name: Check for broken links with lychee + uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0 + with: + fail: true + token: ${{ secrets.GITHUB_TOKEN }} + jobSummary: true + args: | + --root-dir $(pwd)/deploy-staging + --exclude 'file://$(pwd)/deploy-staging/builds' + --exclude 'file://$(pwd)/deploy-staging/projects' + --offline + --no-progress + --remap 'https://docs.nextcloud.com/server/ file://$(pwd)/deploy-staging/server/' + --exclude 'mailto:' + --exclude-path '.*/404\.html' + 'deploy-staging/server/${{ steps.branch.outputs.branch_name }}/**/*.html' + + # ============================================================================ + # DEPLOY + # ============================================================================ + # This job is responsible for: + # 1. Downloading the staged artifacts from stage-and-check + # 2. Applying them to the gh-pages branch + # 3. Creating a pull request for the deployment + # + # This job ONLY runs on pushes (not on pull requests), since we only want + # to deploy when code is merged to master or a stable branch. + # ============================================================================ + deploy: + name: Deploy documentation for gh-pages + needs: stage-and-check + if: github.event_name == 'push' + runs-on: ubuntu-latest permissions: contents: write + pull-requests: write steps: - - name: Cache git metadata - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 - with: - 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/" + - name: Cache git metadata + uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 + with: + path: .git + key: git-metadata-${{ github.sha }} + restore-keys: | + git-metadata-${{ github.sha }} + git-metadata + + - name: Checkout gh-pages branch + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + ref: gh-pages + fetch-depth: 0 + persist-credentials: false + + - name: Download staged artifacts + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: staged-site + path: deploy-staging/ + + # ======================================================================== + # APPLY STAGED ARTIFACTS TO GH-PAGES + # ======================================================================== + # Strategy: + # - Copy from deploy-staging/ to server// + # - If version_name is set, ALSO copy to server// + # - This allows the highest stable to live in both locations + # ======================================================================== + - name: Apply staged artifacts to gh-pages + run: | + branch="${{ needs.stage-and-check.outputs.branch_name }}" + additional="${{ needs.stage-and-check.outputs.additional_deployment }}" + + echo "Deploying to server/${branch}/" + rm -rf "server/${branch}" + cp -r deploy-staging "server/${branch}" + + # If this is the highest stable branch, also deploy to its versioned folder + if [ -n "${additional}" ]; then + echo "Also deploying to server/${additional}/ (additional versioned deployment)" + rm -rf "server/${additional}" + cp -r deploy-staging "server/${additional}" 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: Create Pull Request for documentation deployment - uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0 - id: cpr - with: - token: ${{ secrets.COMMAND_BOT_PAT }} - commit-message: "chore: deploy documentation for ${{ steps.branch.outputs.branch_name }}" - committer: nextcloud-command - author: nextcloud-command - signoff: true - branch: "automated/deploy/documentation-${{ steps.branch.outputs.branch_name }}" - base: gh-pages - title: "Deploy documentation for ${{ steps.branch.outputs.branch_name }}" - body: "Automated documentation deployment from branch ${{ github.ref_name }}" - delete-branch: true - labels: "automated, 3. to review" - - - name: Enable Pull Request Automerge - run: gh pr merge --merge --auto "${{ steps.cpr.outputs.pull-request-number }}" - if: steps.cpr.outputs.pull-request-number != '' - env: - GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }} + + # Clean up empty directories + find . -type d -empty -delete + + # Log the final directory structure for debugging + echo "Final server/ structure:" + find server -type d -maxdepth 2 + + - name: Create Pull Request for documentation deployment + uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0 + id: cpr + with: + token: ${{ secrets.COMMAND_BOT_PAT }} + commit-message: "chore: deploy documentation for ${{ needs.stage-and-check.outputs.branch_name }}" + committer: nextcloud-command + author: nextcloud-command + signoff: true + branch: "automated/deploy/documentation-${{ needs.stage-and-check.outputs.branch_name }}" + base: gh-pages + title: "Deploy documentation for ${{ needs.stage-and-check.outputs.branch_name }}" + body: "Automated documentation deployment from branch ${{ github.ref_name }}" + delete-branch: true + labels: "automated, 3. to review" + + - name: Enable Pull Request Automerge + run: gh pr merge --merge --auto "${{ steps.cpr.outputs.pull-request-number }}" + if: steps.cpr.outputs.pull-request-number != '' + env: + GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }} summary: - needs: build + needs: [build, stage-and-check, deploy] runs-on: ubuntu-latest-low if: always() @@ -305,6 +493,5 @@ jobs: 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 + run: if ${{ needs.build.result != 'success' || needs.stage-and-check.result != 'success' || needs.deploy.result != 'success' }}; then exit 1; fi From 7ff4eb2328612c413a35abc52242c5cd4ad6d749 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 9 Apr 2026 09:47:48 +0200 Subject: [PATCH 5/9] fix(ci): clean up staging artifact structure and deploy logic Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 125 ++++++++++++++++++------------ 1 file changed, 77 insertions(+), 48 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index d314cf3c201..bd9bb2a969f 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -242,7 +242,7 @@ jobs: uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: ref: gh-pages - fetch-depth: 0 + fetch-depth: 1 path: validation-context # ======================================================================== @@ -305,69 +305,78 @@ jobs: echo "Additional deployment folder (if applicable): ${{ steps.branch.outputs.additional_deployment }}" # ======================================================================== - # BUILD FULL DEPLOYMENT STRUCTURE + # ORGANIZE ARTIFACTS FOR DEPLOYMENT # ======================================================================== - # Build the complete gh-pages structure in deploy-staging/ so that: - # 1. Lychee can validate the new content in its actual deployment context - # 2. The staged site includes existing versions (for cross-version link validation) - # 3. The staged site is ready to be copied directly to gh-pages + # Create a clean, minimal staging structure: + # - Deploy only the NEW artifacts for this branch + # - No need to include existing versions (we'll merge them during deploy) # ======================================================================== - - name: Build full deployment structure + - name: Organize artifacts for deployment + id: organize run: | branch="${{ steps.branch.outputs.branch_name }}" - additional="${{ steps.branch.outputs.additional_deployment }}" - # Start with existing gh-pages content (all current versions) - mkdir -p deploy-staging/server - cp -r validation-context/server/* deploy-staging/server/ || true - - # Organize new artifacts into the deployment structure + # Create the branch folder directly mkdir -p "deploy-staging/${branch}" + # Copy artifacts preserving their manual folder structure + # Each artifact (user_manual, admin_manual, developer_manual) contains + # the build output that should be placed in a folder named after the artifact for artifact in artifacts/*; do if [ -d "$artifact" ]; then manual_name="$(basename "$artifact")" - mkdir -p "deploy-staging/${branch}/$manual_name" - cp -r "$artifact/"* "deploy-staging/${branch}/$manual_name/" + # Create the manual-specific folder + mkdir -p "deploy-staging/${branch}/${manual_name}" + # Copy artifact contents into the manual folder + cp -r "$artifact/"* "deploy-staging/${branch}/${manual_name}/" fi done - # Move PDF files to the root of the branch folder - mv "deploy-staging/${branch}"/*/*.pdf "deploy-staging/${branch}/" || true - - # If this is the highest stable, also prepare the additional deployment folder - if [ -n "${additional}" ]; then - mkdir -p "deploy-staging/${additional}" - cp -r "deploy-staging/${branch}"/* "deploy-staging/${additional}/" - fi + # Move PDF files to the root of the branch folder for cleaner structure + find "deploy-staging/${branch}/" -maxdepth 2 -name "*.pdf" -type f -exec mv {} "deploy-staging/${branch}/" \; # Clean up empty directories find deploy-staging -type d -empty -delete - echo "Full deployment structure prepared:" - find deploy-staging -type d -maxdepth 2 + echo "Staged artifacts for ${branch}:" + find deploy-staging -type f | head -20 # ======================================================================== # UPLOAD STAGING ARTIFACTS # ======================================================================== - # Upload only the minimal, organized artifacts needed for deployment. - # The deploy job will download this and place it in the correct location - # on the gh-pages branch. + # Upload only the NEW artifacts in their branch structure. + # The deploy job will handle merging with existing versions on gh-pages. # ======================================================================== - name: Upload staged artifacts uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 with: - name: staged-site + name: staged-documentation-${{ steps.branch.outputs.branch_name }} path: deploy-staging/ # ======================================================================== # VALIDATION: CHECK FOR BROKEN LINKS (NEW CONTENT IN FULL CONTEXT) # ======================================================================== - # Run link checker against the new documentation at deploy-staging//. - # The deploy-staging/ directory includes all existing versions (from - # validation-context/), so lychee can validate cross-version links like - # references to stable/, other version numbers, etc. + # For link validation, we need the full context (existing versions) so + # lychee can resolve cross-version references. So we: + # 1. Build a temporary validation structure with both old and new content + # 2. Run lychee only against the NEW content + # 3. Clean up the temporary structure # ======================================================================== + - name: Build full validation context + run: | + branch="${{ steps.branch.outputs.branch_name }}" + + # Build validation structure: start with existing versions + mkdir -p full-context/server + cp -r validation-context/server/* full-context/server/ || true + + # Merge in the new artifacts + mkdir -p "full-context/server/${branch}" + cp -r "deploy-staging/${branch}/"* "full-context/server/${branch}/" || true + + echo "Validation structure ready:" + find full-context -type d -maxdepth 2 + - name: Check for broken links with lychee uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0 with: @@ -375,15 +384,17 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} jobSummary: true args: | - --root-dir $(pwd)/deploy-staging - --exclude 'file://$(pwd)/deploy-staging/builds' - --exclude 'file://$(pwd)/deploy-staging/projects' + --root-dir $(pwd)/full-context --offline --no-progress - --remap 'https://docs.nextcloud.com/server/ file://$(pwd)/deploy-staging/server/' + --remap 'https://docs.nextcloud.com/server/ file://$(pwd)/full-context/server/' --exclude 'mailto:' --exclude-path '.*/404\.html' - 'deploy-staging/server/${{ steps.branch.outputs.branch_name }}/**/*.html' + 'full-context/server/${{ steps.branch.outputs.branch_name }}/**/*.html' + + - name: Clean up validation context + if: always() + run: rm -rf full-context # ============================================================================ # DEPLOY @@ -420,37 +431,47 @@ jobs: uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: ref: gh-pages - fetch-depth: 0 + fetch-depth: 1 persist-credentials: false - name: Download staged artifacts uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: - name: staged-site - path: deploy-staging/ + name: staged-documentation-${{ needs.stage-and-check.outputs.branch_name }} + path: stage/ # ======================================================================== # APPLY STAGED ARTIFACTS TO GH-PAGES # ======================================================================== # Strategy: - # - Copy from deploy-staging/ to server// + # - Copy from stage// to server// # - If version_name is set, ALSO copy to server// # - This allows the highest stable to live in both locations # ======================================================================== - name: Apply staged artifacts to gh-pages + id: apply run: | branch="${{ needs.stage-and-check.outputs.branch_name }}" additional="${{ needs.stage-and-check.outputs.additional_deployment }}" + changed=0 + + # Deploy to primary branch folder echo "Deploying to server/${branch}/" - rm -rf "server/${branch}" - cp -r deploy-staging "server/${branch}" + if [ -d "stage/${branch}" ]; then + rm -rf "server/${branch}" + mkdir -p "server/${branch}" + cp -r "stage/${branch}/"* "server/${branch}/" || true + changed=1 + fi # If this is the highest stable branch, also deploy to its versioned folder if [ -n "${additional}" ]; then echo "Also deploying to server/${additional}/ (additional versioned deployment)" rm -rf "server/${additional}" - cp -r deploy-staging "server/${additional}" + mkdir -p "server/${additional}" + cp -r "stage/${branch}/"* "server/${additional}/" || true + changed=1 fi # Clean up empty directories @@ -460,19 +481,27 @@ jobs: echo "Final server/ structure:" find server -type d -maxdepth 2 + # Check if there are actual changes + if git diff --quiet HEAD; then + echo "has_changes=false" >> $GITHUB_OUTPUT + else + echo "has_changes=true" >> $GITHUB_OUTPUT + fi + - name: Create Pull Request for documentation deployment uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0 id: cpr + if: steps.apply.outputs.has_changes == 'true' with: token: ${{ secrets.COMMAND_BOT_PAT }} - commit-message: "chore: deploy documentation for ${{ needs.stage-and-check.outputs.branch_name }}" + commit-message: "chore: update documentation for ${{ needs.stage-and-check.outputs.branch_name }}" committer: nextcloud-command author: nextcloud-command signoff: true branch: "automated/deploy/documentation-${{ needs.stage-and-check.outputs.branch_name }}" base: gh-pages - title: "Deploy documentation for ${{ needs.stage-and-check.outputs.branch_name }}" - body: "Automated documentation deployment from branch ${{ github.ref_name }}" + title: "Documentation update for ${{ needs.stage-and-check.outputs.branch_name }}" + body: "Automated documentation update from branch ${{ github.ref_name }}" delete-branch: true labels: "automated, 3. to review" From 930ddd7417c28bceadf6bf814fb5b6982271c988 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 9 Apr 2026 11:28:15 +0200 Subject: [PATCH 6/9] fix(ci): use cache to bundle staged artifacts Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index bd9bb2a969f..1fda71be6dd 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -342,16 +342,16 @@ jobs: find deploy-staging -type f | head -20 # ======================================================================== - # UPLOAD STAGING ARTIFACTS + # CACHE STAGING ARTIFACTS # ======================================================================== - # Upload only the NEW artifacts in their branch structure. - # The deploy job will handle merging with existing versions on gh-pages. + # Cache the staging folder for use in deploy job. + # This avoids artifact storage overhead (saves ~1.8GB). # ======================================================================== - - name: Upload staged artifacts - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 + - name: Cache staged artifacts + uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 with: - name: staged-documentation-${{ steps.branch.outputs.branch_name }} path: deploy-staging/ + key: staged-docs-${{ github.sha }} # ======================================================================== # VALIDATION: CHECK FOR BROKEN LINKS (NEW CONTENT IN FULL CONTEXT) @@ -434,11 +434,12 @@ jobs: fetch-depth: 1 persist-credentials: false - - name: Download staged artifacts - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + - name: Restore staged artifacts from cache + uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 with: - name: staged-documentation-${{ needs.stage-and-check.outputs.branch_name }} path: stage/ + key: staged-docs-${{ github.sha }} + fail-on-cache-miss: true # ======================================================================== # APPLY STAGED ARTIFACTS TO GH-PAGES From 1a4cd036a8223de080e2736c9dc4d38cbd26db8d Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 9 Apr 2026 11:38:23 +0200 Subject: [PATCH 7/9] perf(ci): optimize latex caching Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index 1fda71be6dd..a5f08b3296f 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -34,6 +34,7 @@ jobs: restore-keys: | latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04- latex-apt-${{ runner.os }}-${{ runner.arch }}- + lookup-only: true - name: Download LaTeX packages (cache miss only) if: steps.cache-latex-apt.outputs.cache-hit != 'true' @@ -47,6 +48,13 @@ jobs: # Ensure downloaded packages are owned by the current user so they can be cached sudo chown -R $(id -u):$(id -g) ${{ runner.temp }}/.cache/archives + - name: Save LaTeX apt cache (cache miss only) + if: steps.cache-latex-apt.outputs.cache-hit != 'true' + uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 + with: + path: ${{ runner.temp }}/.cache/archives + key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023 + build: name: Build ${{ matrix.manual.name }} runs-on: ubuntu-latest @@ -121,6 +129,7 @@ jobs: - name: Install LaTeX from cache if: ${{ matrix.manual.build_pdf_path }} + timeout-minutes: 3 run: | sudo DEBIAN_FRONTEND=noninteractive apt-get update sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ @@ -410,7 +419,7 @@ jobs: deploy: name: Deploy documentation for gh-pages needs: stage-and-check - if: github.event_name == 'push' + if: always() runs-on: ubuntu-latest permissions: @@ -495,14 +504,17 @@ jobs: if: steps.apply.outputs.has_changes == 'true' with: token: ${{ secrets.COMMAND_BOT_PAT }} - commit-message: "chore: update documentation for ${{ needs.stage-and-check.outputs.branch_name }}" + commit-message: "chore: update documentation for `${{ needs.stage-and-check.outputs.branch_name }}`" committer: nextcloud-command author: nextcloud-command signoff: true branch: "automated/deploy/documentation-${{ needs.stage-and-check.outputs.branch_name }}" base: gh-pages - title: "Documentation update for ${{ needs.stage-and-check.outputs.branch_name }}" - body: "Automated documentation update from branch ${{ github.ref_name }}" + title: "Documentation update for `${{ needs.stage-and-check.outputs.branch_name }}`" + body: | + This PR was automatically generated by the CI workflow and + includes the latest changes for the `${{ needs.stage-and-check.outputs.branch_name }}` branch. + delete-branch: true labels: "automated, 3. to review" From 14379d7c25b7fee41d7225227c8b840eb89c02cb Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 9 Apr 2026 14:06:26 +0200 Subject: [PATCH 8/9] docs: convert absolute documentation URLs to relative paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace 49 absolute https://docs.nextcloud.com/server/latest/ URLs with relative paths - Improves documentation portability and offline validation - Updates 36 RST files across user_manual, admin_manual, and developer_manual - Maintains .html→.rst conversion and anchor links - Preserves special URLs (OpenAPI, go.php, version 20) --- .github/workflows/sphinxbuild.yml | 1 + .../configuration_files/big_file_upload_configuration.rst | 6 +++--- admin_manual/configuration_files/encryption_details.rst | 2 +- .../configuration_files/file_sharing_configuration.rst | 4 ++-- .../configuration_server/config_sample_php_parameters.rst | 2 +- admin_manual/configuration_user/two_factor-auth.rst | 4 ++-- admin_manual/desktop/index.rst | 4 ++-- admin_manual/index.rst | 4 ++-- admin_manual/installation/example_ubuntu.rst | 2 +- admin_manual/installation/harden_server.rst | 2 +- admin_manual/issues/general_troubleshooting.rst | 4 ++-- admin_manual/occ_command.rst | 6 +++--- .../app_upgrade_guide/upgrade_to_30.rst | 4 ++-- developer_manual/basics/logging.rst | 2 +- developer_manual/basics/setting.rst | 2 +- developer_manual/client_apis/OCS/ocs-share-api.rst | 2 +- developer_manual/desktop/index.rst | 4 ++-- developer_manual/digging_deeper/config/appconfig.rst | 2 +- developer_manual/digging_deeper/config/userconfig.rst | 2 +- developer_manual/digging_deeper/context_chat.rst | 4 ++-- .../exapp_development/faq/DockerSocketProxy.rst | 2 +- .../exapp_development/faq/Troubleshooting.rst | 2 +- .../exapp_development/tech_details/Translations.rst | 2 +- .../exapp_development/tech_details/api/logging.rst | 2 +- developer_manual/getting_started/devenv.rst | 4 ++-- user_manual/desktop/index.rst | 4 ++-- user_manual/external_storage/external_storage.rst | 2 +- user_manual/files/access_webdav.rst | 2 +- user_manual/files/deleted_file_management.rst | 2 +- user_manual/files/encrypting_files.rst | 8 ++++---- user_manual/files/large_file_upload.rst | 2 +- user_manual/files/quota.rst | 2 +- user_manual/files/sharing.rst | 2 +- user_manual/files/transfer_ownership.rst | 2 +- user_manual/groupware/sync_gnome.rst | 2 +- user_manual/groupware/sync_ios.rst | 4 ++-- user_manual/groupware/sync_kde.rst | 2 +- 37 files changed, 55 insertions(+), 54 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index a5f08b3296f..3a50bd5d92a 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -398,6 +398,7 @@ jobs: --no-progress --remap 'https://docs.nextcloud.com/server/ file://$(pwd)/full-context/server/' --exclude 'mailto:' + --exclude '(https?:/?/?)?$' --exclude-path '.*/404\.html' 'full-context/server/${{ steps.branch.outputs.branch_name }}/**/*.html' diff --git a/admin_manual/configuration_files/big_file_upload_configuration.rst b/admin_manual/configuration_files/big_file_upload_configuration.rst index 72ca41bd236..8701e8542ec 100644 --- a/admin_manual/configuration_files/big_file_upload_configuration.rst +++ b/admin_manual/configuration_files/big_file_upload_configuration.rst @@ -45,7 +45,7 @@ relevant php.ini files) :: The ``upload_max_filesize`` and ``post_max_size`` settings may not apply to file uploads through WebDAV single file PUT requests or `Chunked file uploads -`_ +<../../developer_manual/client_apis/WebDAV/chunking.rst>`_ For those, PHP and webserver timeouts are the limiting factor on the upload size. .. TODO ON RELEASE: Update version number above on release @@ -164,7 +164,7 @@ Default is ``104857600`` (100 MiB). Large file upload on object storage ----------------------------------- -`Chunked file uploads `_ +`Chunked file uploads <../../developer_manual/client_apis/WebDAV/chunking.rst>`_ do have a larger space consumption on the temporary folder when processing those uploads on object storage as the individual chunks get downloaded from the storage and will be assembled to the actual file on the Nextcloud servers temporary directory. It is recommended to increase @@ -178,7 +178,7 @@ enough for PHP, webservers or any load balancers involved. Federated Cloud Sharing ----------------------- -If you are using `Federated Cloud Sharing `_ and want to share large files, you can increase the timeout values for requests to the federated servers. +If you are using `Federated Cloud Sharing <../../admin_manual/configuration_files/federated_cloud_sharing_configuration.rst>`_ and want to share large files, you can increase the timeout values for requests to the federated servers. Therefore, you can set ``davstorage.request_timeout`` in your ``config.php``. The default value is 30 seconds. .. TODO ON RELEASE: Update version number above on release diff --git a/admin_manual/configuration_files/encryption_details.rst b/admin_manual/configuration_files/encryption_details.rst index 540c11506bd..2dcabd87bdb 100644 --- a/admin_manual/configuration_files/encryption_details.rst +++ b/admin_manual/configuration_files/encryption_details.rst @@ -346,7 +346,7 @@ Sources ------- - `encryption-recovery-tools repository on GitHub `_ -- `Nextcloud Encryption Configuration documentation `_ +- `Nextcloud Encryption Configuration documentation <../../admin_manual/configuration_files/encryption_configuration.rst>`_ - `Nextcloud Help response concerning the usage of version information `_ - `Sourcecode: Creation of the Message Authentication Code `_ - `Sourcecode: Derivation of the Encryption Key `_ diff --git a/admin_manual/configuration_files/file_sharing_configuration.rst b/admin_manual/configuration_files/file_sharing_configuration.rst index e42ec09314e..86c737f96e2 100644 --- a/admin_manual/configuration_files/file_sharing_configuration.rst +++ b/admin_manual/configuration_files/file_sharing_configuration.rst @@ -98,7 +98,7 @@ forcing them. `_ for discussion of this. .. note:: There are more sharing options on config.php level available: - `Configuration Parameters `_ + `Configuration Parameters <../../admin_manual/configuration_server/config_sample_php_parameters.rst#sharing>`_ .. TODO ON RELEASE: Update version number above on release @@ -176,7 +176,7 @@ Trashbin contents are not transferred:: reference.) Users may also transfer files or folders selectively by themselves. -See `user documentation `_ for details. +See `user documentation <../../user_manual/en/files/transfer_ownership.rst>`_ for details. .. TODO ON RELEASE: Update version number above on release diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index 4202228ab31..b3d596cde15 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -1074,7 +1074,7 @@ Enable SMTP class debugging. .. note:: ``loglevel`` will likely need to be adjusted too. See docs: - https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/email_configuration.html#enabling-debug-mode + ../../admin_manual/configuration_server/email_configuration.rst#enabling-debug-mode Defaults to ``false`` diff --git a/admin_manual/configuration_user/two_factor-auth.rst b/admin_manual/configuration_user/two_factor-auth.rst index 46861aaf287..0bf626ee353 100644 --- a/admin_manual/configuration_user/two_factor-auth.rst +++ b/admin_manual/configuration_user/two_factor-auth.rst @@ -48,7 +48,7 @@ Other 2FA providers may be found in the App Store. .. figure:: ../images/2fa-app-install.png Developers can also `implement new two-factor provider -apps `_. +apps <../../developer_manual/digging_deeper/two-factor-provider.rst>`_. .. TODO ON RELEASE: Update version number above on release @@ -56,7 +56,7 @@ Enforcing two-factor authentication ----------------------------------- By default 2FA is *optional*, hence users are given the choice whether to enable -it for their account `under their personal settings `_. +it for their account `under their personal settings <../../user_manual/en/user_2fa.rst>`_. Admins may, however, enforce the use of 2FA. Enforcement is possible system-wide (all users) or for selected groups only. Select groups diff --git a/admin_manual/desktop/index.rst b/admin_manual/desktop/index.rst index b9a4e213fe1..7810376dfa4 100644 --- a/admin_manual/desktop/index.rst +++ b/admin_manual/desktop/index.rst @@ -27,5 +27,5 @@ You can find additional information here: * `User manual`_ * `Developer manual`_ -.. _`User manual`: https://docs.nextcloud.com/server/latest/user_manual/en/desktop/index.html -.. _`Developer manual`: https://docs.nextcloud.com/server/latest/developer_manual/desktop/index.html +.. _`User manual`: ../../user_manual/en/desktop/index.rst +.. _`Developer manual`: ../../developer_manual/desktop/index.rst diff --git a/admin_manual/index.rst b/admin_manual/index.rst index 85af0a1d253..1798715423e 100644 --- a/admin_manual/index.rst +++ b/admin_manual/index.rst @@ -25,13 +25,13 @@ For documentation on Nextcloud web, desktop, or mobile clients, see: - `Nextcloud User Manual`_ - `Nextcloud Desktop Client`_ -.. _`Nextcloud User Manual`: https://docs.nextcloud.com/server/latest/user_manual/en/ +.. _`Nextcloud User Manual`: ../user_manual/en .. _`Nextcloud Desktop Client`: https://docs.nextcloud.com/desktop/latest/ For documentation on development topics, see: - The individual repositories on GitHub within `the @nextcloud organization `_ -- `Nextcloud Development Manual `_ +- `Nextcloud Development Manual <../developer_manual>`_ .. TODO ON RELEASE: Update version number above on release diff --git a/admin_manual/installation/example_ubuntu.rst b/admin_manual/installation/example_ubuntu.rst index af0b0809272..7cc8377514d 100644 --- a/admin_manual/installation/example_ubuntu.rst +++ b/admin_manual/installation/example_ubuntu.rst @@ -14,7 +14,7 @@ following commands in a terminal:: * This installs the packages for the Nextcloud core system. If you are planning on running additional apps, keep in mind that they might - require additional packages. See `Prerequisites for manual installation `_ for details. + require additional packages. See `Prerequisites for manual installation <../../admin_manual/installation/source_installation.rst#prerequisites-for-manual-installation>`_ for details. .. TODO ON RELEASE: Update version number above on release diff --git a/admin_manual/installation/harden_server.rst b/admin_manual/installation/harden_server.rst index 4b24fcb9aea..4bd8aacc5b0 100644 --- a/admin_manual/installation/harden_server.rst +++ b/admin_manual/installation/harden_server.rst @@ -302,7 +302,7 @@ Depending on your server setup, these are the possible connections: - Any remote Nextcloud server that is connected with federated sharing - When downloading apps from the App store other domains might be accessed, based on the choice of the app developers where they host the releases. For all official Nextcloud apps this is not the case though, because they are hosted on Github. -.. _optional (config): https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#has-internet-connection +.. _optional (config): ../../admin_manual/configuration_server/config_sample_php_parameters.rst#has-internet-connection .. _detailed field list: https://github.com/nextcloud/survey_client .. TODO ON RELEASE: Update version number above on release diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index 93b4acf4375..067bf0b8332 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -31,7 +31,7 @@ configuration report with the :ref:`occ config command .. _the Nextcloud Forums: https://help.nextcloud.com .. _FAQ page: https://help.nextcloud.com/t/how-to-faq-wiki -.. _bugtracker: https://docs.nextcloud.com/server/latest/developer_manual/prologue/bugtracker/index.html +.. _bugtracker: ../../developer_manual/prologue/bugtracker/index.rst .. TODO ON RELEASE: Update version number above on release @@ -413,7 +413,7 @@ does not match the actual data stored in the user's ``data/$userId/files`` direc .. note:: Metadata, versions, trashbin and encryption keys are not counted in the used space above. - Please refer to the `quota documentation `_ for details. + Please refer to the `quota documentation <../../user_manual/en/files/quota.rst>`_ for details. .. TODO ON RELEASE: Update version number above on release diff --git a/admin_manual/occ_command.rst b/admin_manual/occ_command.rst index 40117bb3907..10f2f6850c7 100644 --- a/admin_manual/occ_command.rst +++ b/admin_manual/occ_command.rst @@ -373,7 +373,7 @@ While setting a configuration value, multiple options are available: .. note:: See `Appconfig Concepts`_ to learn more about `typed value`, `lazy` and `sensitive` flag. -.. _Appconfig Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/appconfig.html#concept-overview +.. _Appconfig Concepts: ../developer_manual/digging_deeper/config/appconfig.rst#concept-overview .. TODO ON RELEASE: Update version number above on release @@ -1148,7 +1148,7 @@ The command line option ``--transfer-incoming-shares`` overwrites the config.php sudo -E -u www-data php occ files:transfer-ownership --transfer-incoming-shares=0 Users may also transfer files or folders selectively by themselves. -See `user documentation `_ for details. +See `user documentation <../user_manual/en/files/transfer_ownership.rst>`_ for details. .. TODO ON RELEASE: Update version number above on release @@ -1241,7 +1241,7 @@ Verify your app:: sudo -E -u www-data php occ integrity:check-app --path=/pathto/app appname When it returns nothing, your app is signed correctly. When it returns a message then there is an error. See `Code Signing -`_ in the Developer manual for more detailed information. +<../developer_manual/app_publishing_maintenance/code_signing.rst#how-to-get-your-app-signed>`_ in the Developer manual for more detailed information. .. TODO ON RELEASE: Update version number above on release diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_30.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_30.rst index 50d43536328..dd22778010c 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_30.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_30.rst @@ -191,7 +191,7 @@ Added APIs - ``OCP\Console\ReservedOptions`` was added and contains constants for options reserved for occ core features. ``--debug-log`` and ``--debug-log-level`` are now reserved by occ as they allow to show debug information to the output on any occ command. - ``OCP\Security\IHasher::validate()`` should return true if the passed string is a valid hash generated by ``OCP\Security\IHasher::hash()`` - ``OCP\AppFramework\Http\JSONResponse()`` constructor now supports passing additional ``json_encode`` flags, see https://www.php.net/manual/en/function.json-encode.php for details -- ``OCP\EventDispatcher\IWebhookCompatibleEvent`` is a new interface for events compatible with webhooks (`see webhook_listeners documentation `_). +- ``OCP\EventDispatcher\IWebhookCompatibleEvent`` is a new interface for events compatible with webhooks (`see webhook_listeners documentation <../../../admin_manual/webhook_listeners/index.rst>`_). - ``OCP\EventDispatcher\JsonSerializer`` is a new public helper for serializing users and fileinfos to json (ie for webhook events) Changed APIs @@ -222,7 +222,7 @@ Changed APIs - ``OCP\IUserManager::getDisabledUsers`` now has a third parameter for a search string. - ``OCP\User\Backend\IProvideEnabledStateBackend::getDisabledUserList`` now has a third parameter for a search string. - Legacy class ``OC_EventSource`` was moved to ``OC`` namespace with the ``OC_`` prefix. It should not change anything if you already correctly use the ``OCP\IEventSourceFactory`` to create these objects. -- ``OCP\Files\Events\Node\AbstractNodeEvent`` and ``OCP\Files\Events\Node\AbstractNodesEvent`` now implements ``OCP\EventDispatcher\IWebhookCompatibleEvent`` so that all file/folder related events are available for webhooks (`see webhook_listeners documentation `_). +- ``OCP\Files\Events\Node\AbstractNodeEvent`` and ``OCP\Files\Events\Node\AbstractNodesEvent`` now implements ``OCP\EventDispatcher\IWebhookCompatibleEvent`` so that all file/folder related events are available for webhooks (`see webhook_listeners documentation <../../../admin_manual/webhook_listeners/index.rst>`_). Deprecated APIs ^^^^^^^^^^^^^^^ diff --git a/developer_manual/basics/logging.rst b/developer_manual/basics/logging.rst index 8dac7fbde4e..9e9c20a23bc 100644 --- a/developer_manual/basics/logging.rst +++ b/developer_manual/basics/logging.rst @@ -47,7 +47,7 @@ Admin audit logging If you want to log things less for system administration but for compliance reasons, e.g. who accessed which file, who changed the password of an item or made it public, the -`admin audit log `_ +`admin audit log <../../admin_manual/configuration_server/logging_configuration.rst#admin-audit-log>`_ is the correct place. .. TODO ON RELEASE: Update version number above on release diff --git a/developer_manual/basics/setting.rst b/developer_manual/basics/setting.rst index 5e15bbb9f12..173f4c1fddd 100644 --- a/developer_manual/basics/setting.rst +++ b/developer_manual/basics/setting.rst @@ -110,7 +110,7 @@ The last missing part is to register both classes inside **/appinfo/info. `` instead. Additionally since Nextcloud 23, groups can be granted authorization to access individual -admin settings (`see admin docs `_). +admin settings (`see admin docs <../../admin_manual/configuration_server/admin_delegation_configuration.rst>`_). This is a feature that needs to be enabled for each admin setting class. To do so, the setting class needs to implement `IDelegatedSettings` instead of `ISettings` and implement two additional methods. diff --git a/developer_manual/client_apis/OCS/ocs-share-api.rst b/developer_manual/client_apis/OCS/ocs-share-api.rst index 167a84aa3ce..953509e961e 100644 --- a/developer_manual/client_apis/OCS/ocs-share-api.rst +++ b/developer_manual/client_apis/OCS/ocs-share-api.rst @@ -225,7 +225,7 @@ Federated Cloud Shares ---------------------- Both the sending and the receiving instance need to have federated cloud sharing -enabled and configured. See `Configuring Federated Cloud Sharing `_. +enabled and configured. See `Configuring Federated Cloud Sharing <../../../admin_manual/configuration_files/federated_cloud_sharing_configuration.rst>`_. .. TODO ON RELEASE: Update version number above on release diff --git a/developer_manual/desktop/index.rst b/developer_manual/desktop/index.rst index 38811125f95..7df9dc4327e 100644 --- a/developer_manual/desktop/index.rst +++ b/developer_manual/desktop/index.rst @@ -21,5 +21,5 @@ You can find additional information here: * `User manual`_ * `Admin manual`_ -.. _`User manual`: https://docs.nextcloud.com/server/latest/user_manual/en/desktop/index.html -.. _`Admin manual`: https://docs.nextcloud.com/server/latest/admin_manual/desktop/index.html +.. _`User manual`: ../../user_manual/en/desktop/index.rst +.. _`Admin manual`: ../../admin_manual/desktop/index.rst diff --git a/developer_manual/digging_deeper/config/appconfig.rst b/developer_manual/digging_deeper/config/appconfig.rst index 6fd3e683e42..3a2c0d82c73 100644 --- a/developer_manual/digging_deeper/config/appconfig.rst +++ b/developer_manual/digging_deeper/config/appconfig.rst @@ -24,7 +24,7 @@ In addition to simple read/write operations, ``IAppConfig`` supports: .. note:: See `Lexicon Concepts`_ to learn more about **Lexicon**, a way to define configuration keys and avoid conflicts in your code. -.. _Lexicon Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/lexicon.html#concept-overview +.. _Lexicon Concepts: ../../../developer_manual/digging_deeper/config/lexicon.rst#concept-overview AppFramework diff --git a/developer_manual/digging_deeper/config/userconfig.rst b/developer_manual/digging_deeper/config/userconfig.rst index b50e66d7bc8..a5cf834be55 100644 --- a/developer_manual/digging_deeper/config/userconfig.rst +++ b/developer_manual/digging_deeper/config/userconfig.rst @@ -18,7 +18,7 @@ On top of storing and accessing your configuration values, ``IUserConfig`` comes .. note:: See `Lexicon Concepts`_ to learn more about **Lexicon**, a way to fully define your configuration keys and avoid conflict when using it in your code. -.. _Lexicon Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/lexicon.html#concept-overview +.. _Lexicon Concepts: ../../../developer_manual/digging_deeper/config/lexicon.rst#concept-overview Typed Config Values diff --git a/developer_manual/digging_deeper/context_chat.rst b/developer_manual/digging_deeper/context_chat.rst index 462233dd56e..58c214da3c1 100644 --- a/developer_manual/digging_deeper/context_chat.rst +++ b/developer_manual/digging_deeper/context_chat.rst @@ -7,8 +7,8 @@ Context Chat .. versionadded:: 32.0.0 Nextcloud offers a **Context Chat** API which allows apps like files to submit data -to the `Nextcloud Assistant Context Chat `_, -thereby enabling `Nextcloud Assistant `_ +to the `Nextcloud Assistant Context Chat <../../admin_manual/ai/app_context_chat.rst>`_, +thereby enabling `Nextcloud Assistant <../../admin_manual/ai/app_assistant.rst>`_ to answer questions, provide insights and search results based on the submitted data and natural language queries. Implementing a content provider for Context Chat diff --git a/developer_manual/exapp_development/faq/DockerSocketProxy.rst b/developer_manual/exapp_development/faq/DockerSocketProxy.rst index fc1f4fe7b8b..445c919c4d4 100644 --- a/developer_manual/exapp_development/faq/DockerSocketProxy.rst +++ b/developer_manual/exapp_development/faq/DockerSocketProxy.rst @@ -28,7 +28,7 @@ Nextcloud AIO implements its own `Docker Socket Proxy container `_ for more details. +See `Nextcloud in Docker AIO (all-in-one) <../../../admin_manual/exapps_management/DeployConfigurations.rst#nextcloud-in-docker-aio-all-in-one>`_ for more details. .. TODO ON RELEASE: Update version number above on release diff --git a/developer_manual/exapp_development/faq/Troubleshooting.rst b/developer_manual/exapp_development/faq/Troubleshooting.rst index 432d8b7ab38..dd5abac44c1 100644 --- a/developer_manual/exapp_development/faq/Troubleshooting.rst +++ b/developer_manual/exapp_development/faq/Troubleshooting.rst @@ -27,7 +27,7 @@ Here are some common steps to verify the network configuration: ExApp deployment issues ----------------------- -The deployment issues questions are covered in the `Test Deploy `_ section of the administration guide. +The deployment issues questions are covered in the `Test Deploy <../../../admin_manual/exapps_management/TestDeploy.rst>`_ section of the administration guide. Generally speaking, there are three steps to find the proper error message to understand the problem: .. TODO ON RELEASE: Update version number above on release diff --git a/developer_manual/exapp_development/tech_details/Translations.rst b/developer_manual/exapp_development/tech_details/Translations.rst index 1d9a2f27200..d6f78cd0970 100644 --- a/developer_manual/exapp_development/tech_details/Translations.rst +++ b/developer_manual/exapp_development/tech_details/Translations.rst @@ -43,7 +43,7 @@ You can then compile them to ``.mo`` files using `ui_example's `_ ``l10n`` folder of the ExApp +For the ``manual-install`` type, an administrator will have to manually extract to the server's `writable apps directory <../../../admin_manual/configuration_server/config_sample_php_parameters.rst#apps-paths>`_ ``l10n`` folder of the ExApp (e.g. ``/path/to/apps-writable//l10n/*.(js|json)``). This will allow the server to access the ExApp's strings with translations. diff --git a/developer_manual/exapp_development/tech_details/api/logging.rst b/developer_manual/exapp_development/tech_details/api/logging.rst index 9464a470a3d..a26533c7e93 100644 --- a/developer_manual/exapp_development/tech_details/api/logging.rst +++ b/developer_manual/exapp_development/tech_details/api/logging.rst @@ -25,7 +25,7 @@ Request data } -The possible values of ``log_lvl`` are described here: `Nextcloud Log level `_ +The possible values of ``log_lvl`` are described here: `Nextcloud Log level <../../../../admin_manual/configuration_server/logging_configuration.rst#log-level>`_ .. TODO ON RELEASE: Update version number above on release diff --git a/developer_manual/getting_started/devenv.rst b/developer_manual/getting_started/devenv.rst index 7d9fb281efc..4976cc01982 100644 --- a/developer_manual/getting_started/devenv.rst +++ b/developer_manual/getting_started/devenv.rst @@ -16,7 +16,7 @@ Please follow the steps on this page to set up your development environment manu Set up Web server and database ------------------------------ -First `set up your Web server and database `_ (**Section**: Manual Installation - Prerequisites). +First `set up your Web server and database <../../admin_manual/installation/index.rst>`_ (**Section**: Manual Installation - Prerequisites). .. TODO ON RELEASE: Update version number above on release @@ -25,7 +25,7 @@ Get the source There are two ways to obtain Nextcloud sources: -* Using the `stable version `_ +* Using the `stable version <../../admin_manual/installation/index.rst>`_ * Using the development version from `GitHub`_ which will be explained below. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/desktop/index.rst b/user_manual/desktop/index.rst index 5d20c9b54f3..8fa89dd7cce 100644 --- a/user_manual/desktop/index.rst +++ b/user_manual/desktop/index.rst @@ -27,7 +27,7 @@ You can find additional information here: * `Admin manual`_ * `Developer manual`_ -.. _`Admin manual`: https://docs.nextcloud.com/server/latest/admin_manual/desktop/index.html -.. _`Developer manual`: https://docs.nextcloud.com/server/latest/developer_manual/desktop/index.html +.. _`Admin manual`: ../../admin_manual/desktop/index.rst +.. _`Developer manual`: ../../developer_manual/desktop/index.rst .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/external_storage/external_storage.rst b/user_manual/external_storage/external_storage.rst index da9a0810319..022a1b80574 100644 --- a/user_manual/external_storage/external_storage.rst +++ b/user_manual/external_storage/external_storage.rst @@ -6,7 +6,7 @@ The External Storage application allows you to mount external storage services, such as Amazon S3, SMB/CIFS file servers and FTP servers… in Nextcloud. Your Nextcloud server administrator controls which of these are available to you. Please see `Configuring External Storage (GUI) -`_ in the Nextcloud Administrator's +<../../admin_manual/configuration_files/external_storage_configuration_gui.rst>`_ in the Nextcloud Administrator's manual for configuration how-tos and examples. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/files/access_webdav.rst b/user_manual/files/access_webdav.rst index 1aab65124d7..9f9e5c2ead3 100644 --- a/user_manual/files/access_webdav.rst +++ b/user_manual/files/access_webdav.rst @@ -222,7 +222,7 @@ path of your certificate as in this example:: Accessing files using macOS --------------------------- -.. note:: The macOS Finder suffers from a `series of implementation problems `_ and should only be used if the Nextcloud server runs on **Apache** and **mod_php**, or **Nginx 1.3.8+**. Alternative macOS-compatible clients capable of accessing WebDAV shares include open source apps like `Cyberduck `_ (see instructions `here `_) and `Filezilla `_. Commercial clients include `Mountain Duck `_, `Forklift `_, `Transmit `_, and `Commander One `_. +.. note:: The macOS Finder suffers from a `series of implementation problems `_ and should only be used if the Nextcloud server runs on **Apache** and **mod_php**, or **Nginx 1.3.8+**. Alternative macOS-compatible clients capable of accessing WebDAV shares include open source apps like `Cyberduck `_ (see instructions `here <../../user_manual/files/access_webdav.rst#accessing-files-using-cyberduck>`_) and `Filezilla `_. Commercial clients include `Mountain Duck `_, `Forklift `_, `Transmit `_, and `Commander One `_. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/files/deleted_file_management.rst b/user_manual/files/deleted_file_management.rst index 8684a76147a..d95cd8711bb 100644 --- a/user_manual/files/deleted_file_management.rst +++ b/user_manual/files/deleted_file_management.rst @@ -56,6 +56,6 @@ Nextcloud will permanently delete those trashed files with the soonest expiratio until the space limit is met again. .. note:: Your administrator may have configured the trash bin retention period - to override the storage space management. See `admin documentation `_ for more details. + to override the storage space management. See `admin documentation <../../admin_manual/configuration_server/config_sample_php_parameters.rst#deleted-items-trash-bin>`_ for more details. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/files/encrypting_files.rst b/user_manual/files/encrypting_files.rst index 50398945a2d..82fa2a4b360 100644 --- a/user_manual/files/encrypting_files.rst +++ b/user_manual/files/encrypting_files.rst @@ -34,7 +34,7 @@ How can encryption be disabled? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The only way to disable encryption is to run the `"decrypt all" -`_ +<../../admin_manual/occ_command.rst#encryption-label>`_ script, which decrypts all files and disables encryption. .. TODO ON RELEASE: Update version number above on release @@ -43,8 +43,8 @@ Is it possible to disable encryption with the recovery key? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Yes, *if* every user uses the `file recovery key -`_, `"decrypt all" -`_ will use it to decrypt all files. +<../../admin_manual/configuration_files/encryption_configuration.rst#enabling-users-file-recovery-keys>`_, `"decrypt all" +<../../admin_manual/occ_command.rst#encryption-label>`_ will use it to decrypt all files. .. TODO ON RELEASE: Update version number above on release @@ -52,7 +52,7 @@ Can encryption be disabled without the user's password? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you don't have the users password or `file recovery key -`_, +<../../admin_manual/configuration_files/encryption_configuration.rst#enabling-users-file-recovery-keys>`_, then there is no way to decrypt all files. What's more, running it on login would be dangerous, because you would most likely run into timeouts. diff --git a/user_manual/files/large_file_upload.rst b/user_manual/files/large_file_upload.rst index cf39c1c2fe7..10852c1b85d 100644 --- a/user_manual/files/large_file_upload.rst +++ b/user_manual/files/large_file_upload.rst @@ -9,7 +9,7 @@ Modifying certain Nextcloud variables requires administrative access. If you req * Contact your administrator to request an increase in these variables * Refer to the section in the `Administration Documentation - `_ that describes how to manage file + <../../admin_manual/configuration_files/big_file_upload_configuration.rst>`_ that describes how to manage file upload size limits. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/files/quota.rst b/user_manual/files/quota.rst index 93eeda0923f..c673985d05b 100644 --- a/user_manual/files/quota.rst +++ b/user_manual/files/quota.rst @@ -29,7 +29,7 @@ deleted files exceed 50% of quota then the oldest files are removed until the total is below 50%. .. note:: Your administrator may have configured the trash bin retention period - to override the storage space management. See `administrator documentation `_ for more details. + to override the storage space management. See `administrator documentation <../../admin_manual/configuration_server/config_sample_php_parameters.rst#deleted-items-trash-bin>`_ for more details. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/files/sharing.rst b/user_manual/files/sharing.rst index ba960b930a6..e6178020857 100644 --- a/user_manual/files/sharing.rst +++ b/user_manual/files/sharing.rst @@ -12,7 +12,7 @@ Nextcloud users can share files and folders. Possible targets are: * users or groups on federated Nextcloud servers .. note:: Some options may not be available due to administrative configuration. - See `administrator documentation `__ for details. + See `administrator documentation <../../admin_manual/configuration_files/file_sharing_configuration.rst>`__ for details. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/files/transfer_ownership.rst b/user_manual/files/transfer_ownership.rst index 97cc75c2490..302ca3d261e 100644 --- a/user_manual/files/transfer_ownership.rst +++ b/user_manual/files/transfer_ownership.rst @@ -13,7 +13,7 @@ ownerships of those transferred files/folders will also be transferred. #. Click on *Transfer*. .. note:: The username autocompletion or listing may be limited due to administrative visibility configuration. - See `administrator documentation `_ for details. + See `administrator documentation <../../admin_manual/configuration_files/file_sharing_configuration.rst>`_ for details. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/groupware/sync_gnome.rst b/user_manual/groupware/sync_gnome.rst index 4d42c58577a..692bbaa420b 100644 --- a/user_manual/groupware/sync_gnome.rst +++ b/user_manual/groupware/sync_gnome.rst @@ -15,7 +15,7 @@ This can be done by following these steps: #. Enter your server URL, username, and password. If you have enabled two-factor authentication (2FA), you need to generate an application password/token, because GNOME Online Accounts `doesn't support Nextcloud's WebFlow login yet `_ - (`Learn more `_): + (`Learn more <../../user_manual/en/session_management.rst#managing-devices>`_): .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/groupware/sync_ios.rst b/user_manual/groupware/sync_ios.rst index be23255f195..da1a0f58728 100644 --- a/user_manual/groupware/sync_ios.rst +++ b/user_manual/groupware/sync_ios.rst @@ -53,7 +53,7 @@ You should now find your contacts in the address book of your iPhone. If it's still not working, have a look at `Troubleshooting Contacts & Calendar`_ or `Troubleshooting Service Discovery`_. -.. _Troubleshooting Contacts & Calendar: https://docs.nextcloud.com/server/latest/admin_manual/issues/general_troubleshooting.html#troubleshooting-contacts-calendar -.. _Troubleshooting Service Discovery: https://docs.nextcloud.com/server/latest/admin_manual/issues/general_troubleshooting.html#service-discovery +.. _Troubleshooting Contacts & Calendar: ../../admin_manual/issues/general_troubleshooting.rst#troubleshooting-contacts-calendar +.. _Troubleshooting Service Discovery: ../../admin_manual/issues/general_troubleshooting.rst#service-discovery .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/groupware/sync_kde.rst b/user_manual/groupware/sync_kde.rst index a3b42eb4fb1..fc3eb4e7c78 100644 --- a/user_manual/groupware/sync_kde.rst +++ b/user_manual/groupware/sync_kde.rst @@ -28,7 +28,7 @@ In Kalendar: In KOrganizer and Kalendar: -3. Enter your username. As password, you need to generate an app-password/token (`Learn more `_): +3. Enter your username. As password, you need to generate an app-password/token (`Learn more <../../user_manual/en/session_management.rst#managing-devices>`_): .. TODO ON RELEASE: Update version number above on release From 7206b88e91c490fdae7f054a5a2827ef558cd82e Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 9 Apr 2026 14:24:24 +0200 Subject: [PATCH 9/9] fix(ci): correct cache path mismatch between stage-and-check and deploy jobs - Standardize cache staging directory from 'deploy-staging/' to 'stage/' - Ensures cache save and restore paths match - Fixes 'fail-on-cache-miss: true' cache miss error - Updates all references in organize, cache, and validation steps Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index 3a50bd5d92a..1ec6ab49962 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -326,7 +326,7 @@ jobs: branch="${{ steps.branch.outputs.branch_name }}" # Create the branch folder directly - mkdir -p "deploy-staging/${branch}" + mkdir -p "stage/${branch}" # Copy artifacts preserving their manual folder structure # Each artifact (user_manual, admin_manual, developer_manual) contains @@ -335,20 +335,20 @@ jobs: if [ -d "$artifact" ]; then manual_name="$(basename "$artifact")" # Create the manual-specific folder - mkdir -p "deploy-staging/${branch}/${manual_name}" + mkdir -p "stage/${branch}/${manual_name}" # Copy artifact contents into the manual folder - cp -r "$artifact/"* "deploy-staging/${branch}/${manual_name}/" + cp -r "$artifact/"* "stage/${branch}/${manual_name}/" fi done # Move PDF files to the root of the branch folder for cleaner structure - find "deploy-staging/${branch}/" -maxdepth 2 -name "*.pdf" -type f -exec mv {} "deploy-staging/${branch}/" \; + find "stage/${branch}/" -maxdepth 2 -name "*.pdf" -type f -exec mv {} "stage/${branch}/" \; # Clean up empty directories - find deploy-staging -type d -empty -delete + find stage -type d -empty -delete echo "Staged artifacts for ${branch}:" - find deploy-staging -type f | head -20 + find stage -type f | head -20 # ======================================================================== # CACHE STAGING ARTIFACTS @@ -359,7 +359,7 @@ jobs: - name: Cache staged artifacts uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4 with: - path: deploy-staging/ + path: stage/ key: staged-docs-${{ github.sha }} # ======================================================================== @@ -381,7 +381,7 @@ jobs: # Merge in the new artifacts mkdir -p "full-context/server/${branch}" - cp -r "deploy-staging/${branch}/"* "full-context/server/${branch}/" || true + cp -r "stage/${branch}/"* "full-context/server/${branch}/" || true echo "Validation structure ready:" find full-context -type d -maxdepth 2 @@ -398,7 +398,6 @@ jobs: --no-progress --remap 'https://docs.nextcloud.com/server/ file://$(pwd)/full-context/server/' --exclude 'mailto:' - --exclude '(https?:/?/?)?$' --exclude-path '.*/404\.html' 'full-context/server/${{ steps.branch.outputs.branch_name }}/**/*.html' @@ -499,6 +498,10 @@ jobs: echo "has_changes=true" >> $GITHUB_OUTPUT fi + # Remove the stage/ directory BEFORE creating the PR so it doesn't get committed + - name: Clean up staging cache before commit + run: rm -rf stage/ + - name: Create Pull Request for documentation deployment uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0 id: cpr