Separate linkcheck job from doc building by AVHopp · Pull Request #898 · emdgroup/baybe

AVHopp · 2026-08-18T15:06:44Z

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.

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

AVHopp · 2026-08-18T15:07:49Z

        run: |
          pip install tox-uv
          tox -e docs-py311 -- -r
+


Original post by @Scienfitz

there are two conceptual design choices in this PR that to me seemingly defy the purpose of its intended achivement

The linkcheck takes way too long, we are not gaining very much anything by doing that. Does it moslty stem from the environment install?
The doc building should depend on the linkbuild with the idea being that the long docbuild only is attempted if the fast linkcheck worked out -> "fail fast"

@Scienfitz, I do not think that we can get much faster. From what I see, the link checking just seems to be so slow because the doc is "compiled" first. I can do a more detailed analysis if interested.

well the probme is that the linkcheck is cosntructed such that t needs an isntalled otx env, which isthe thing that takes a long time, right?

I can only point this ot at the moment, I havent really looked into the logic yet, main aim would be to understand whether the current path taken is the right/only one or if there are faster things possible

Naive example: it should be quick to use grep/regex etc to scan through links and check them, not python env or doc building needed. But I cant jughe how many links wed miss that way

Moving away from sphinx for linkchecking is a nice idea. Will investigate

AVHopp · 2026-08-18T15:09:27Z

  `BayesianRecommender`
 - `Parameter.is_equivalent` method for structural parameter comparison
 - `posterior_mean_function` method to `GaussianProcessSurrogate`
+- Dedicated job for checking internal links in the documentation


Comment from @AdrianSosic : not sure if needed, not user facing

AVHopp · 2026-08-18T15:10:34Z

Original comment from copilot:

check_links.py runs sphinx-build directly, but the docs toctree includes examples/examples (generated into docs/examples/ by build_examples). In a fresh CI checkout this directory doesn't exist, so linkcheck will at least warn about missing documents and may skip checking links that live in generated example pages. Consider creating dummy examples (or otherwise ensuring docs/examples exists) before running Sphinx linkcheck.

My original answer: @AdrianSosic @Scienfitz this is something we actually need to discuss: How important is checking external links in the examples for us? This would require us to fully build the examples here, making this job significantly slower, and I think we actually do have links in the examples. Opinions?

Answer from @AdrianSosic : would we get the alert in the second run? if yes, then I think it's fine to miss the cases in the first run

No, since we do not check links in the second run. If we want to check external links in the examples, then we need to run the examples in the link checking, increasing the running time quite significantly

if the linkcheck cannot be pulled out to enable an early fail, what would be the purpose of this change?

I have now changed this in 51ac6a5: We now convert the examples, but do not execute during link checking. This then takes a bit more time, but not as much as when fully executing them, and is sufficient for checking the links. Would this be a good compromise?

why would examples ever be executed to be checked for links? Can the execution have an impact on a link validity?

If you do not do execution I would expect the linkcheck to be faster, not slower? can you elaborate?

did you consider whether things between these two steps could be shared? e.g. if things the linkcheck step already converted/built are not repeatedly converted/built on the second docbuild stage? Files could be shared (via artifacts or similar). That would enable at least that we do not get any added time, but the time from the docbuild would be "pulled forward" to the linkcheck. Maybe even the tox env can be shared?

I originally thought that execution might be necessary due to our way of converting the examples. Turns out this was incorrect, conversion into the format that sphinx can handle can be done without needing to execute them

Previously, the separated linkcheck did not check the links in the examples at all. Now that it checks the links in the examples, it is slower.

I did try a bit, mainly via caching (which did not work), but not too much. I can check if artifact sharing might be possible and easy, good idea!

Note: Will consider if we can simply step away from sphinx for linkchecking, depending on the outcome of this I will share some more insights here.

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.

AVHopp · 2026-08-19T07:15:58Z

BLOCKER: Check first that this builds the documentation properly on my fork

Checking of external links is no longer handled by the `linkcheck` builder. The `dummy ` builder is used instead, which does not check external links but still checks internal links.

Copilot AI lite review requested due to automatic review settings August 18, 2026 15:06

AVHopp requested review from AdrianSosic and Scienfitz as code owners August 18, 2026 15:06

Copilot started reviewing on behalf of AVHopp August 18, 2026 15:07 View session

AVHopp commented Aug 18, 2026

View reviewed changes

Copilot AI reviewed Aug 18, 2026

View reviewed changes

Comment thread docs/scripts/check_links.py

Comment thread CHANGELOG.md Outdated

AVHopp force-pushed the docs/separate_linkcheck_new branch from 51ac6a5 to be0aaa7 Compare August 19, 2026 07:08

AVHopp force-pushed the docs/separate_linkcheck_new branch from be0aaa7 to 297738c Compare August 19, 2026 07:12

AVHopp commented Aug 19, 2026

View reviewed changes

AVHopp marked this pull request as draft August 20, 2026 08:56

AVHopp force-pushed the docs/separate_linkcheck_new branch from 3e48b15 to 297738c Compare August 20, 2026 09:38

AVHopp closed this Aug 20, 2026

AVHopp force-pushed the docs/separate_linkcheck_new branch from 297738c to 24125fa Compare August 20, 2026 09:49

AVHopp reopened this Aug 20, 2026

AVHopp changed the base branch from docs/refactor-apidoc_new to docs/parallelize_example_execution August 20, 2026 10:45

AVHopp marked this pull request as ready for review August 20, 2026 10:46

AVHopp marked this pull request as draft August 20, 2026 10:49

AVHopp force-pushed the docs/separate_linkcheck_new branch from 56edeec to c4068b9 Compare August 20, 2026 11:01

AVHopp marked this pull request as ready for review August 20, 2026 11:02

AVHopp force-pushed the docs/separate_linkcheck_new branch from c4068b9 to 9e3a794 Compare August 20, 2026 11:18

AVHopp marked this pull request as draft August 20, 2026 13:32

AVHopp self-assigned this Aug 20, 2026

AVHopp force-pushed the docs/separate_linkcheck_new branch 2 times, most recently from fa70d27 to 14e9af8 Compare August 31, 2026 08:13

AVHopp force-pushed the docs/separate_linkcheck_new branch from 14e9af8 to 584e9b9 Compare August 31, 2026 08:49

AVHopp force-pushed the docs/separate_linkcheck_new branch from 584e9b9 to 3b0ecd2 Compare August 31, 2026 11:49

AVHopp force-pushed the docs/separate_linkcheck_new branch from 3b0ecd2 to 7d647f6 Compare August 31, 2026 12:14

AVHopp force-pushed the docs/separate_linkcheck_new branch from 7d647f6 to ee438cc Compare September 1, 2026 06:42

AVHopp force-pushed the docs/separate_linkcheck_new branch 2 times, most recently from a091454 to d206f85 Compare September 1, 2026 14:42

AVHopp force-pushed the docs/separate_linkcheck_new branch 2 times, most recently from 3ab4a7b to f453363 Compare September 1, 2026 14:52

AVHopp added 6 commits September 1, 2026 17:19

Use lychee for linkchecking

ea0045c

Use dummy instead of linkcheck builder

5ff0e9d

Checking of external links is no longer handled by the `linkcheck` builder. The `dummy ` builder is used instead, which does not check external links but still checks internal links.

Specify root-dir for lychee

b95d732

Add --verbose flag

00d445f

Use more verbose output for lychee

657127d

Remove -n and -W flags from dummy build

22d45fe

AVHopp force-pushed the docs/separate_linkcheck_new branch from f453363 to 22d45fe Compare September 1, 2026 15:21

Uh oh!

Conversation

AVHopp commented Aug 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Scienfitz Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Scienfitz Aug 19, 2026 •

edited

Loading