Add sphinx-lint CI for RST files

[Copilot]

Adds sphinx-lint as a dedicated CI linting step for the three manuals, and fixes all pre-existing violations so the check passes cleanly from day one.

CI workflow (.github/workflows/sphinx-lint.yml)

• Lightweight job on ubuntu-latest, separate from the heavy sphinxbuild.yml (no PDF/Docker)
• Triggers on pull_request + push to master/stable*
• Runs sphinx-lint --disable trailing-whitespace --disable horizontal-tab — those two checks have thousands of pre-existing violations that need incremental cleanup; all other checks are enforced

requirements.txt

• Added sphinx-lint==1.0.2 (pinned, consistent with rest of file)
• Workflow install command is also pinned to the same version to prevent drift

Pre-existing violations fixed (38 total)

Category	Count	Files
Missing final newline	27	Various across all three manuals
Malformed hyperlinks	3	app_summary_bot.rst, upgrade_to_20.rst, sync_windows10.rst
Unbalanced inline literals	3	ocs-openapi.rst, upgrade_to_33.rst
Role markup errors	4	server_tuning.rst, filesystem.rst, commandline.rst, ocs-openapi.rst
Dangling hyphen	1	sync_windows10.rst — URL ending in - in a link definition; converted to inline hyperlink

☑️ Resolves

🖼️ Screenshots

✅ Checklist

• I have built the documentation locally and reviewed the output
• Screenshots are included for visual changes
• I have not moved or renamed pages (or added a redirect if I did)
• I have run codespell or similar and addressed any spelling issues

Original prompt

Add sphinx-lint to CI

Add sphinx-lint as a CI linting step for RST files across all three manuals.

Changes required

1. requirements.txt

Add sphinx-lint pinned to a recent stable version (e.g. 1.0.0), consistent with the existing pinning strategy for all other dependencies in the file.

2. New workflow .github/workflows/sphinx-lint.yml

Create a dedicated lightweight workflow modelled after .github/workflows/codespell.yml. It should:

• Trigger on pull_request and push to master and stable* branches
• Use permissions: contents: read
• Run on ubuntu-latest
• Check out the repo (use the same pinned actions/checkout SHA already used in other workflows: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd)
• Set up Python 3.13 with pip cache (use the same pinned actions/setup-python SHA: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405)
• Install sphinx-lint via pip
• Run sphinx-lint against admin_manual developer_manual user_manual

Notes

• Keep the workflow separate from sphinxbuild.yml to avoid the heavy PDF/Docker overhead
• Only lint the three manual directories to avoid false positives from vendored/generated content
• If there are many pre-existing violations, add continue-on-error: true to the lint step as a temporary measure to allow incremental fixing — but only if needed

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

User: How would you approach adding sphinx lint to CI ?

Assistant: Here's how I'd approach adding sphinx-lint to CI in this repo:

Approach

1. Add sphinx-lint to requirements.txt

# add this line:
sphinx-lint==1.0.0

Pin it like all the other dependencies for reproducibility.

2. Add a dedicated workflow .github/workflows/sphinx-lint.yml

Modelling it after the existing codespell.yml (simple, lightweight linting job):

name: 'Sphinx Lint'

on:
  pull_request:
  push:
    branches:
      - master
      - stable*

permissions:
  contents: read

jobs:
  sphinx-lint:
    name: Lint RST files
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.13"
          cache: "pip"

      - name: Install sphinx-lint
        run: pip install sphinx-lint

      - name: Run sphinx-lint
        run: sphinx-lint admin_manual developer_manual user_manual

Key design decisions

Decision	Rationale
Separate workflow	Keeps lint fast and independent from the heavy sphinxbuild.yml (no PDF/Docker overhead)
Lint only the 3 manual dirs	Avoids false positives from vendored/generated files in _shared_assets, build/, etc.
ubuntu-latest not self-hosted	codespell uses self-hosted, but since sphinx-lint is a pure pip install it's cheap and fine on a standard runner
Also triggers on stable*	Matches the sphinxbuild triggers, since RST quality matters on all maintained branches
Pin version in requirements.txt	Keeps it consistent with the repo's pinning strategy for all other deps

3. (Optional) Iterative rollout if there are pre-existing warnings

If running sphinx-lint locally reveals a lot of existing issues, you can start non-blocking by adding continue-on-error: true to the lint step, then fix violations incrementally and remove the flag once the baseline is clean. This avoids a big noisy PR.

# Run locally first to gauge the blast radius:
pip install sphinx-lint
sphinx-lint admin_manual developer_manual user_manual

Would you like me to open a PR with these changes?

User: Ok, go

Assistant: The coding agent is now working on the PR. It will:

1. Add sphinx-lint to requirements.txt
2. Create .github/workflows/sphinx-lint.yml as a dedicated, lightweight linting workflow

You'll see the PR appear in nextcloud/documentation shortly. I'll note that if there are lots of pre-existing RST violations, the agent may add continue-on-error: true as a temporary measure so the PR isn't blocked — you can clean those up incrementally and drop that flag afterward.

This pull request was created from Copilot chat.

[skjnldsv]

• Runs sphinx-lint --disable trailing-whitespace --disable horizontal-tab — those two checks have thousands of pre-existing violations that need incremental cleanup; all other checks are enforced

We'll fix them later

[github-actions]

📖 Documentation Preview

🔍 Open preview →

📄 35 changed documentation pages

• admin_manual/ai/app_summary_bot.rst
• admin_manual/ai/eu_ai_act.rst
• admin_manual/ai/insight_and_debugging.rst
• admin_manual/collectives/index.rst
• admin_manual/configuration_user/authentication.rst
• admin_manual/file_workflows/configuration.rst
• admin_manual/installation/server_tuning.rst
• admin_manual/installation/uninstallation.rst
• admin_manual/office/installation.rst
• admin_manual/office/migration.rst
• developer_manual/app_publishing_maintenance/maintainer.rst
• developer_manual/app_publishing_maintenance/release_automation.rst
• developer_manual/basics/storage/filesystem.rst
• developer_manual/client_apis/OCS/ocs-openapi.rst
• developer_manual/client_apis/OCS/ocs-recommendations-api.rst
• developer_manual/digging_deeper/groupware/mail_provider.rst
• developer_manual/digging_deeper/web_host_metadata.rst
• developer_manual/html_css_design/css.rst
• developer_manual/release_notes/previous/upgrade_to_20.rst
• developer_manual/release_notes/previous/upgrade_to_33.rst
  …and 15 more. View all changed files

Last updated: Wed, 06 May 2026 08:08:52 GMT

[skjnldsv]

/backport to stable33

[skjnldsv]

/backport to stable32

[backportbot]

The backport to stable33 failed. Please do this backport manually.

# Switch to the target branch and update it
git checkout stable33
git pull origin stable33

# Create the new backport branch
git checkout -b backport/14769/stable33

# Cherry pick the change from the commit sha1 of the change against the default branch
# This might cause conflicts, resolve them
git cherry-pick ae8a2ddf da96ed6a 2fdbc702 afaf0ec8

# Push the cherry pick commit to the remote repository and open a pull request
git push origin backport/14769/stable33

Error: Failed to check for changes with origin/stable33: No changes found in backport branch

---

Learn more about backports at https://docs.nextcloud.com/server/stable/go.php?to=developer-backports.

[backportbot]

The backport to stable32 failed. Please do this backport manually.

# Switch to the target branch and update it
git checkout stable32
git pull origin stable32

# Create the new backport branch
git checkout -b backport/14769/stable32

# Cherry pick the change from the commit sha1 of the change against the default branch
# This might cause conflicts, resolve them
git cherry-pick ae8a2ddf da96ed6a 2fdbc702 afaf0ec8

# Push the cherry pick commit to the remote repository and open a pull request
git push origin backport/14769/stable32

Error: Failed to check for changes with origin/stable32: No changes found in backport branch

---

Learn more about backports at https://docs.nextcloud.com/server/stable/go.php?to=developer-backports.