Skip to content

DOC: Use warnings instead of exceptions in gallery order#31831

Merged
QuLogic merged 1 commit into
matplotlib:mainfrom
timhoffm:doc-gallery-order-warning
Jun 5, 2026
Merged

DOC: Use warnings instead of exceptions in gallery order#31831
QuLogic merged 1 commit into
matplotlib:mainfrom
timhoffm:doc-gallery-order-warning

Conversation

@timhoffm
Copy link
Copy Markdown
Member

@timhoffm timhoffm commented Jun 5, 2026

Exceptions cause a hard exit of sphinx, which is undesirable. Incorrect order specification should not break the build. It also make fixes harder since one gets the first ordering issue and possibly would have to do multiple builds to see and fix multiple ordering issues.

The warning will now look like this:

WARNING: The following examples are not listed in galleries/examples/spines/gallery_order.txt. Either include them or add a '*' to indicate where not listed examples should be placed: spines_dropped.py

@timhoffm
DOC: Use warnings instead of exceptions in gallery order
e04a9fa 
Exceptions cause a hard exit of sphinx, which is undesirable. Incorrect order specification should not break the build. It also make fixes harder since one one gets the first ordering issue and possibly would have to do multiple builds to see and fix multiple ordering issues.
@timhoffm timhoffm added this to the v3.11.0 milestone Jun 5, 2026
@github-actions github-actions Bot added the Documentation: build building the docs label Jun 5, 2026
@scottshambaugh
Copy link
Copy Markdown
Contributor

scottshambaugh commented Jun 5, 2026

Do we still raise on missing examples, not just wrong-ordered ones?

@QuLogic
Copy link
Copy Markdown
Member

QuLogic commented Jun 5, 2026

If I delete a line, then we get:

WARNING: The following examples are not listed in galleries/examples/spines/gallery_order.txt. Either include them or add a '*' to indicate where not listed examples should be placed: spine_placement_demo.py

If I add an extra line, we get:

WARNING: The following examples listed in galleries/plot_types/stats/gallery_order.txt do not exist: foobar.py

and at the end we have:

build finished with problems, 2 warnings (with warnings treated as errors).
make: *** [Makefile:50: html] Error 1
make: Leaving directory '/home/elliott/code/matplotlib/doc'

So essentially, we moved from a single hard failure, to possibly multiple warnings, that are still a failure at the end.

@QuLogic QuLogic merged commit 3f865e5 into matplotlib:main Jun 5, 2026
24 checks passed
@meeseeksmachine meeseeksmachine mentioned this pull request Jun 5, 2026
Merged
@timhoffm timhoffm deleted the doc-gallery-order-warning branch June 5, 2026 20:11
timhoffm pushed a commit that referenced this pull request Jun 5, 2026
@QuLogic @meeseeksmachine
Backport PR #31831: DOC: Use warnings instead of exceptions in galler…
ad521c8 
…y order
timhoffm added a commit that referenced this pull request Jun 5, 2026
@timhoffm
Merge pull request #31850 from meeseeksmachine/auto-backport-of-pr-31…
2ad60d3 
…831-on-v3.11.x

Backport PR #31831 on branch v3.11.x (DOC: Use warnings instead of exceptions in gallery order)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@QuLogic QuLogic QuLogic approved these changes

@story645 story645 story645 approved these changes

Assignees

No one assigned

Labels

Documentation: build building the docs

Projects

None yet

Milestone

v3.11.0

Development

Successfully merging this pull request may close these issues.

4 participants

@timhoffm @scottshambaugh @QuLogic @story645