From c983d0ae7e751371af48e12838f959d70e758809 Mon Sep 17 00:00:00 2001 From: Aman Srivastava Date: Sat, 7 Feb 2026 02:53:41 +0530 Subject: [PATCH 1/5] DOC: Reorder Irradiance Transposition example gallery section --- ..._ghi_transposition.py => 01_ghi_transposition.py} | 0 ...ransposition_gain.py => 02_transposition_gain.py} | 0 ...n_error.py => 03_interval_transposition_error.py} | 0 ...erez_modelchain.py => 04_use_perez_modelchain.py} | 0 ..._mixed_orientation.py => 05_mixed_orientation.py} | 0 .../{plot_seasonal_tilt.py => 06_seasonal_tilt.py} | 0 ...{plot_rtranpose_year.py => 07_rtranspose_year.py} | 0 ...e_limitations.py => 08_rtranspose_limitations.py} | 0 docs/sphinx/source/contributing/style_guide.rst | 12 ++++++++++++ 9 files changed, 12 insertions(+) rename docs/examples/irradiance-transposition/{plot_ghi_transposition.py => 01_ghi_transposition.py} (100%) rename docs/examples/irradiance-transposition/{plot_transposition_gain.py => 02_transposition_gain.py} (100%) rename docs/examples/irradiance-transposition/{plot_interval_transposition_error.py => 03_interval_transposition_error.py} (100%) rename docs/examples/irradiance-transposition/{use_perez_modelchain.py => 04_use_perez_modelchain.py} (100%) rename docs/examples/irradiance-transposition/{plot_mixed_orientation.py => 05_mixed_orientation.py} (100%) rename docs/examples/irradiance-transposition/{plot_seasonal_tilt.py => 06_seasonal_tilt.py} (100%) rename docs/examples/irradiance-transposition/{plot_rtranpose_year.py => 07_rtranspose_year.py} (100%) rename docs/examples/irradiance-transposition/{plot_rtranpose_limitations.py => 08_rtranspose_limitations.py} (100%) diff --git a/docs/examples/irradiance-transposition/plot_ghi_transposition.py b/docs/examples/irradiance-transposition/01_ghi_transposition.py similarity index 100% rename from docs/examples/irradiance-transposition/plot_ghi_transposition.py rename to docs/examples/irradiance-transposition/01_ghi_transposition.py diff --git a/docs/examples/irradiance-transposition/plot_transposition_gain.py b/docs/examples/irradiance-transposition/02_transposition_gain.py similarity index 100% rename from docs/examples/irradiance-transposition/plot_transposition_gain.py rename to docs/examples/irradiance-transposition/02_transposition_gain.py diff --git a/docs/examples/irradiance-transposition/plot_interval_transposition_error.py b/docs/examples/irradiance-transposition/03_interval_transposition_error.py similarity index 100% rename from docs/examples/irradiance-transposition/plot_interval_transposition_error.py rename to docs/examples/irradiance-transposition/03_interval_transposition_error.py diff --git a/docs/examples/irradiance-transposition/use_perez_modelchain.py b/docs/examples/irradiance-transposition/04_use_perez_modelchain.py similarity index 100% rename from docs/examples/irradiance-transposition/use_perez_modelchain.py rename to docs/examples/irradiance-transposition/04_use_perez_modelchain.py diff --git a/docs/examples/irradiance-transposition/plot_mixed_orientation.py b/docs/examples/irradiance-transposition/05_mixed_orientation.py similarity index 100% rename from docs/examples/irradiance-transposition/plot_mixed_orientation.py rename to docs/examples/irradiance-transposition/05_mixed_orientation.py diff --git a/docs/examples/irradiance-transposition/plot_seasonal_tilt.py b/docs/examples/irradiance-transposition/06_seasonal_tilt.py similarity index 100% rename from docs/examples/irradiance-transposition/plot_seasonal_tilt.py rename to docs/examples/irradiance-transposition/06_seasonal_tilt.py diff --git a/docs/examples/irradiance-transposition/plot_rtranpose_year.py b/docs/examples/irradiance-transposition/07_rtranspose_year.py similarity index 100% rename from docs/examples/irradiance-transposition/plot_rtranpose_year.py rename to docs/examples/irradiance-transposition/07_rtranspose_year.py diff --git a/docs/examples/irradiance-transposition/plot_rtranpose_limitations.py b/docs/examples/irradiance-transposition/08_rtranspose_limitations.py similarity index 100% rename from docs/examples/irradiance-transposition/plot_rtranpose_limitations.py rename to docs/examples/irradiance-transposition/08_rtranspose_limitations.py diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 4eea571eda..954ed3495a 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -350,3 +350,15 @@ Here is a starter template for new examples: For more details, see the sphinx-gallery `docs `_. + +Controlling Example Order +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Examples within a subsection are ordered alphabetically by filename. +To control their position explicitly, prefix filenames with numbers +(e.g., ``01_``, ``02_``). + +For more advanced ordering options, see the sphinx-gallery +`documentation `_. + + From b86435ab29ea0681187d17d1bad1104546fe4ef8 Mon Sep 17 00:00:00 2001 From: Aman Srivastava Date: Tue, 10 Feb 2026 00:10:04 +0530 Subject: [PATCH 2/5] control irradiance-transposition gallery order via custom sort key --- docs/sphinx/source/conf.py | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 0415acb644..0ff8deeb68 100644 --- a/docs/sphinx/source/conf.py +++ b/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 From 06fe1e1bc31f09bc0e7e2f1864477044d58988d6 Mon Sep 17 00:00:00 2001 From: Aman Srivastava Date: Tue, 10 Feb 2026 00:52:32 +0530 Subject: [PATCH 3/5] writing to style guide --- .../source/contributing/style_guide.rst | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 954ed3495a..cde0bc7374 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -354,11 +354,16 @@ For more details, see the sphinx-gallery Controlling Example Order ~~~~~~~~~~~~~~~~~~~~~~~~~ -Examples within a subsection are ordered alphabetically by filename. -To control their position explicitly, prefix filenames with numbers -(e.g., ``01_``, ``02_``). - -For more advanced ordering options, see the sphinx-gallery -`documentation `_. - - +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 +`_. From 745308945d8ff45524331873392fbba4d82e7252 Mon Sep 17 00:00:00 2001 From: Aman Srivastava Date: Tue, 10 Feb 2026 01:16:35 +0530 Subject: [PATCH 4/5] restore original irradiance-transposition example filenames --- .../{01_ghi_transposition.py => plot_ghi_transposition.py} | 0 ...ransposition_error.py => plot_interval_transposition_error.py} | 0 .../{05_mixed_orientation.py => plot_mixed_orientation.py} | 0 ...08_rtranspose_limitations.py => plot_rtranpose_limitations.py} | 0 .../{07_rtranspose_year.py => plot_rtranpose_year.py} | 0 .../{06_seasonal_tilt.py => plot_seasonal_tilt.py} | 0 .../{02_transposition_gain.py => plot_transposition_gain.py} | 0 .../{04_use_perez_modelchain.py => use_perez_modelchain.py} | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename docs/examples/irradiance-transposition/{01_ghi_transposition.py => plot_ghi_transposition.py} (100%) rename docs/examples/irradiance-transposition/{03_interval_transposition_error.py => plot_interval_transposition_error.py} (100%) rename docs/examples/irradiance-transposition/{05_mixed_orientation.py => plot_mixed_orientation.py} (100%) rename docs/examples/irradiance-transposition/{08_rtranspose_limitations.py => plot_rtranpose_limitations.py} (100%) rename docs/examples/irradiance-transposition/{07_rtranspose_year.py => plot_rtranpose_year.py} (100%) rename docs/examples/irradiance-transposition/{06_seasonal_tilt.py => plot_seasonal_tilt.py} (100%) rename docs/examples/irradiance-transposition/{02_transposition_gain.py => plot_transposition_gain.py} (100%) rename docs/examples/irradiance-transposition/{04_use_perez_modelchain.py => use_perez_modelchain.py} (100%) diff --git a/docs/examples/irradiance-transposition/01_ghi_transposition.py b/docs/examples/irradiance-transposition/plot_ghi_transposition.py similarity index 100% rename from docs/examples/irradiance-transposition/01_ghi_transposition.py rename to docs/examples/irradiance-transposition/plot_ghi_transposition.py diff --git a/docs/examples/irradiance-transposition/03_interval_transposition_error.py b/docs/examples/irradiance-transposition/plot_interval_transposition_error.py similarity index 100% rename from docs/examples/irradiance-transposition/03_interval_transposition_error.py rename to docs/examples/irradiance-transposition/plot_interval_transposition_error.py diff --git a/docs/examples/irradiance-transposition/05_mixed_orientation.py b/docs/examples/irradiance-transposition/plot_mixed_orientation.py similarity index 100% rename from docs/examples/irradiance-transposition/05_mixed_orientation.py rename to docs/examples/irradiance-transposition/plot_mixed_orientation.py diff --git a/docs/examples/irradiance-transposition/08_rtranspose_limitations.py b/docs/examples/irradiance-transposition/plot_rtranpose_limitations.py similarity index 100% rename from docs/examples/irradiance-transposition/08_rtranspose_limitations.py rename to docs/examples/irradiance-transposition/plot_rtranpose_limitations.py diff --git a/docs/examples/irradiance-transposition/07_rtranspose_year.py b/docs/examples/irradiance-transposition/plot_rtranpose_year.py similarity index 100% rename from docs/examples/irradiance-transposition/07_rtranspose_year.py rename to docs/examples/irradiance-transposition/plot_rtranpose_year.py diff --git a/docs/examples/irradiance-transposition/06_seasonal_tilt.py b/docs/examples/irradiance-transposition/plot_seasonal_tilt.py similarity index 100% rename from docs/examples/irradiance-transposition/06_seasonal_tilt.py rename to docs/examples/irradiance-transposition/plot_seasonal_tilt.py diff --git a/docs/examples/irradiance-transposition/02_transposition_gain.py b/docs/examples/irradiance-transposition/plot_transposition_gain.py similarity index 100% rename from docs/examples/irradiance-transposition/02_transposition_gain.py rename to docs/examples/irradiance-transposition/plot_transposition_gain.py diff --git a/docs/examples/irradiance-transposition/04_use_perez_modelchain.py b/docs/examples/irradiance-transposition/use_perez_modelchain.py similarity index 100% rename from docs/examples/irradiance-transposition/04_use_perez_modelchain.py rename to docs/examples/irradiance-transposition/use_perez_modelchain.py From 8a692ddc0875dd255fd7230a8fca09f8b72fddb4 Mon Sep 17 00:00:00 2001 From: Aman Srivastava Date: Tue, 10 Feb 2026 01:25:41 +0530 Subject: [PATCH 5/5] Trigger CI rerun