Use lychee for docbuilding

[AVHopp]

This PR separates the linkcheck job from the actual doc building. It does so by creating a new dedicated job for it in the CI and re-organizing the code.

External link checking

• Replace Sphinx's linkcheck builder with lychee for external URL validation
• Add a standalone lychee CI job that scans baybe/, docs/, examples/, and top-level markdown files
• Configure exclusions in lychee.toml (migrated from linkcheck_ignore in docs/conf.py)
• Remove the now-unused linkcheck_ignore from docs/conf.py

Cross-reference checking

• Switch the Sphinx build in check_links.py from linkcheck to dummy builder, which validates internal cross-references (:class:, :func:, :meth:, intersphinx) without rendering HTML
• The dummy builder runs without -n/-W flags because it cannot fully resolve intersphinx references (e.g. ArrayLike), which would cause false positives; the html build with -n -W checks those

Naming cleanup

• Rename things related to check_links to change_crossrefs

CI changes

• Add lychee job to ci.yml, gating build-docs on both lint and lychee

Misc

• The CI job shows all links that have been checked or excluded. Excluded links are the internal ones (as those are handled by sphinx). At the end of that job there is also a short summary (see screenshots)
• We would also be able use lychee for internal links but since the sphinx html build already does this, there is no further speed-up that we can gain here.
• Up-to-date version of the fork is available at https://avhopp.github.io/baybe_dev/latest/ (built after my latest commits answering to the first review of @Scienfitz )

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Pull request overview

This PR restructures BayBE’s documentation CI so external link checking is run as a dedicated step/job instead of being embedded in the documentation build script, and it tunes Sphinx linkcheck settings to make the new gating behavior more reliable.

Changes:

• Adds a dedicated linkcheck tox environment and wires it into GitHub Actions (including a separate CI job).
• Removes linkcheck logic/flags from docs/scripts/build_documentation.py and enables parallel Sphinx builds.
• Configures Sphinx linkcheck behavior (ignore patterns + timeout/retries) for more stable CI runs.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tox.ini	Adds testenv:linkcheck and updates docs-quickbuild to match the new separation.
docs/scripts/check_links.py	Updates linkcheck utility and adds parallel build flag.
docs/scripts/build_documentation.py	Removes linkcheck flag/logic and enables parallel Sphinx HTML build.
docs/conf.py	Adds linkcheck ignore/timeout/retry settings to reduce flaky failures.
CHANGELOG.md	Notes the new documentation linkcheck job.
.github/workflows/docs.yml	Runs linkcheck explicitly before building/publishing docs.
.github/workflows/ci.yml	Introduces a dedicated linkcheck job and makes docs build depend on it.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Scienfitz]

If I understand the PR desc correctly lychee only checks external links, but could also check internal crossrefs like for code objects too
is that correct?

the PR desc mentions this wouldnt bring speedbut, but the whole point of pre-performed linkcheck is also to enable fail-early, not overall speedup (whichis a benefit on top but not needed)

[AVHopp]

Yes. The issue is that it could only properly check those links in the fully build documentation (source: Independent querying of ChatGPT and Claude Code, checking their docs manually: "Out of the box lychee supports HTML, Markdown and plain text formats.") So we would need to fully build the html documentation first anyway, and building this already checks for broken cross refs (tested)

[Copilot]

🟡 Changes recommended

Three moderate review findings remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

.github/workflows/ci.yml:90

• Moving external-link checking out of build_documentation.py also changes the separate .github/workflows/docs.yml publish path: it still runs the build script on main pushes, releases, and manual runs, but it has no lychee step or dependency. The needs: [lint, lychee] here cannot gate that separate workflow, so documentation can still be published without external-link validation; add lychee to the publishing workflow or otherwise make publication depend on the check if that path is in scope.

  build-docs:
    name: "Build Docs"
    runs-on: ubuntu-latest
    needs: [lint, lychee]

• Files reviewed: 6/6 changed files
• Comments generated: 2
• Review effort level: Lite

[AVHopp]

@Scienfitz @AdrianSosic I overlooked this in my first implementation. Added it now as I assume that we also want to have link checking when actually building the documentation, not only in the CI. Feel free to resolve once you have seen this.