From ad521c84f340e2c2a95253df7cf135ad04d19032 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Fri, 5 Jun 2026 15:40:54 -0400 Subject: [PATCH] Backport PR #31831: DOC: Use warnings instead of exceptions in gallery order --- doc/sphinxext/gallery_order.py | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/doc/sphinxext/gallery_order.py b/doc/sphinxext/gallery_order.py index 140280344e81..048a856c69e0 100644 --- a/doc/sphinxext/gallery_order.py +++ b/doc/sphinxext/gallery_order.py @@ -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 @@ -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 @@ -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)}"