Reorder Irradiance Transposition example gallery section

docs/sphinx/source/conf.py

@@ -384,6 +384,32 @@ def setup(app):
 # https://github.com/pvlib/pvlib-python/issues/837
 suppress_warnings = ['ref.footnote']
 
+
+def irradiance_transposition_sort_key(filename):
+    order = [
+        "plot_ghi_transposition.py",
+        "plot_transposition_gain.py",
+        "plot_interval_transposition_error.py",
+        "use_perez_modelchain.py",
+        "plot_mixed_orientation.py",
+        "plot_seasonal_tilt.py",
+        "plot_rtranpose_year.py",
+        "plot_rtranpose_limitations.py",
+    ]
+
+    subsection = os.path.basename(os.path.dirname(filename))
+
+    if subsection == "irradiance-transposition":
+        name = os.path.basename(filename)
+        if name in order:
+            return (0, order.index(name))
+        else:
+            return (0, len(order))
+
+    # For everything else, fall back to filename sorting
+    return (1, filename)
+
+
 # settings for sphinx-gallery
 sphinx_gallery_conf = {
     'examples_dirs': ['../../examples'],  # location of gallery scripts
@@ -400,6 +426,9 @@ def setup(app):
 
     # https://sphinx-gallery.github.io/dev/configuration.html#removing-config-comments  # noqa: E501
     'remove_config_comments': True,
+
+    # Explicit ordering for irradiance-transposition subsection
+    'within_subsection_order': irradiance_transposition_sort_key,
 }
 # supress warnings in gallery output
 # https://sphinx-gallery.github.io/stable/configuration.html

docs/sphinx/source/contributing/style_guide.rst

@@ -350,3 +350,20 @@ Here is a starter template for new examples:
 
 For more details, see the sphinx-gallery
 `docs <https://sphinx-gallery.github.io/stable/syntax.html#embedding-rst>`_.
+
+Controlling Example Order
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Examples within a subsection are ordered according to the
+``within_subsection_order`` setting defined in ``conf.py``.
+
+By default, Sphinx-Gallery applies its built-in sorting behavior.
+To explicitly control the order of examples, configure
+``within_subsection_order`` in ``docs/sphinx/source/conf.py``.
+This may be set to one of Sphinx-Gallery's built-in sort keys
+(e.g., ``FileNameSortKey`` or ``ExampleTitleSortKey``),
+or to a custom callable for fine-grained control.
+
+See the Sphinx-Gallery documentation for details:
+`Gallery examples
+<https://sphinx-gallery.github.io/stable/configuration.html#sorting-gallery-examples>`_.