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.

[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