Skip to content

Do not build notebooks when doing linkcheck #272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nvaytet merged 3 commits into from
Jan 23, 2026
Merged

Do not build notebooks when doing linkcheck #272

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
055377f
do not build notebooks when doing linkcheck
nvaytet Jan 17, 2026
6460870
do not build for linkcheck
nvaytet Jan 19, 2026
8a6d200
Merge branch 'main' into no-build-when-linkcheck
nvaytet Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions template/tox.ini.jinja
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ description = invoke sphinx-build to build the HTML docs
deps = -r requirements/docs.txt
allowlist_externals=find
commands = python -m sphinx -W -j2 -v -b html -d {toxworkdir}/docs_doctrees docs html
python -m sphinx -W -j2 -v -b doctest -d {toxworkdir}/docs_doctrees docs html
python -m sphinx -W -j2 -v -b doctest -d {toxworkdir}/docs_doctrees -D nbsphinx_execute=never docs html
Comment on lines 29 to +30
Copy link
Member

@SimonHeybrock SimonHeybrock Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is doctest, linkcheck is 15 lines lower down, did you edit the wrong one or is the PR title wrong?

Copy link
Member Author

@nvaytet nvaytet Jan 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I meant to edit the linkcheck line.

However, can we also skip building when doing doctest? Do I remember correctly that doctest is testing snippets in the docs, but not what is run in notebook cells?

Copy link
Member

@SimonHeybrock SimonHeybrock Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, probably?

Copy link
Member Author

@nvaytet nvaytet Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jl-wynen do you know if not running notebooks for doctest is ok?

Copy link
Member

@jl-wynen jl-wynen Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't it use the cached results anyway since we build the docs in the line above?

I would think that we don't need to execute notebooks for doctest because we don't have code samples in the notebooks. But we do need to execute them for linkcheck so we can check the links in notebooks. Would be nice if we could reuse the cached results from the docs build in that case.

Copy link
Member Author

@nvaytet nvaytet Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need to run the notebooks just to check links in the markdown cells?

Copy link
Member

@jl-wynen jl-wynen Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think linkcheck can handle markdown or notebooks on its own. AFAIK, it operates on the parse tree generated by docutils which require rst.

Copy link
Member

@jl-wynen jl-wynen Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I may well be wrong!

Copy link
Member Author

@nvaytet nvaytet Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nbsphinx will still render rst files from the notebooks, it just won't execute the code in the cells (so there will be no outputs in the generated docs).

To prove it, I tried to insert a bad link in one of the notebooks in essdiffraction and it found it:

(user-guide/dream/dream-advanced-powder-reduction: line   12) broken    https://scipppp.github.io/ - 404 Client Error: Not Found for url: https://scipppp.github.io/

Other links are checked and validated properly:
Screenshot_20260123_110009

Copy link
Member

@jl-wynen jl-wynen Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then I have no objections.

find html -type f -name "*.ipynb" -not -path "html/_sources/*" -delete

[testenv:releasedocs]
Expand All @@ -42,7 +42,7 @@ commands = {[testenv:docs]commands}
[testenv:linkcheck]
description = Run Sphinx linkcheck
deps = -r requirements/docs.txt
commands = python -m sphinx -j2 -v -b linkcheck -d {toxworkdir}/docs_doctrees docs html
commands = python -m sphinx -j2 -v -b linkcheck -d {toxworkdir}/docs_doctrees -D nbsphinx_execute=never docs html

[testenv:static]
description = Code formatting and static analysis
Expand Down