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 diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 4eea571eda..cde0bc7374 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/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 `_. + +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 +`_.