Skip to content

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

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
QuLogic merged 1 commit into from
Jun 5, 2026
+9 −5
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 9 additions & 5 deletions doc/sphinxext/gallery_order.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@
from pathlib import Path

from sphinx_gallery.sorting import ExplicitOrder
from sphinx.util import logging as sphinx_logging

logger = sphinx_logging.getLogger(__name__)

# Gallery sections shall be displayed in the following order.
# Non-matching sections are inserted at the unsorted position
Expand Down Expand Up @@ -98,7 +101,7 @@ class MplFileExplicitOrder(ExplicitOrder):
Use this if you want to ensure that a full order is intentionally maintained.
"""
def __init__(self, src_dir):
ordered_list = self.read_gallery_order(Path(src_dir)) or []
ordered_list = self.read_gallery_order(Path(src_dir).resolve()) or []
super().__init__(ordered_list)

@staticmethod
Expand Down Expand Up @@ -135,13 +138,14 @@ def read_gallery_order(src_dir: Path):
non_existing_examples = listed_examples - existing_examples
missing_examples = existing_examples - listed_examples

rel_txt_path = gallery_order_txt.relative_to(gallery_order_txt.parents[3])
if non_existing_examples:
raise ValueError(
f"The following examples listed in {gallery_order_txt} do not exist: "
logger.warning(
f"The following examples listed in {rel_txt_path} do not exist: "
f"{', '.join(non_existing_examples)}")
if placeholder_index is None and missing_examples:
raise ValueError(
f"The following examples are not listed in {gallery_order_txt}. "
logger.warning(
f"The following examples are not listed in {rel_txt_path}. "
f"Either include them or add a '*' to indicate where not listed "
f"examples should be placed: "
f"{', '.join(missing_examples)}"
Expand Down
Loading