How to organize the example gallery?

[kandersolar]

The example gallery now has 17 items and might benefit from being organized into sections. This has been briefly discussed elsewhere:

• Add gallery example for cross-axis slope backtracking  #1077 (comment)
• Mount gallery examples #1266 (comment)

I think the sphinx configuration changes to do this would be straightforward (see here). The question is how the gallery should be organized. For inspiration, here are some other packages with sections in their gallery:

• matplotlib: https://matplotlib.org/stable/gallery/index.html
• metpy: https://unidata.github.io/MetPy/latest/examples/index.html
• sunpy: https://docs.sunpy.org/en/stable/generated/gallery/index.html
• cartopy: https://scitools.org.uk/cartopy/docs/latest/gallery/index.html
• scikit-learn: https://scikit-learn.org/stable/auto_examples/index.html
• probably other ones listed here: https://sphinx-gallery.github.io/stable/projects_list.html

To get the conversation started, here are some categorizations mentioned in the above threads:

• by abstraction level: functions vs objects
• by task (or "how do I"), e.g. system modeling vs resource assessment vs ...
• by modeling topic, roughly along the lines of the pvlib module breakdown and PVPMC diagram

Input from anyone is welcome!

[mikofski]

I think I like by module? EG:

• solar position
• irradiance
• atmosphere
• clearsky
• PV modules
• inverters
• IO
• IV curves
• PV systems
• etc

This could incorporate both topics and abstraction level, bc objects tend to aggregate several functions across topics. Each section could have both "how to's" and other less general examples

[kandersolar]

I'm not sure I like organizing by module, in part because some of these examples span multiple modules (Modeling with interval averages: solar position or irradiance?). What do folks think about the proposed topic-based organization below? It's mostly the same as module-based, but I think it might be clearer.

• Transposition: Mixed Orientation, GHI to POA Transposition, Seasonal Tilt, Modeling Transposition Gain, Modeling with interval averages
• Tracking: Single-axis tracking, Dual-Axis Tracking, Backtracking on sloped terrain, Discontinuous Tracking
• I-V Modeling: Calculating a module's IV curves
• Solar Position: Sun path diagram
• Soiling: Kimber Soiling Model, HSU Soiling Model Example
• Shading: Diffuse Self Shading, Calculating power loss from partial module shading
• Reflections: Diffuse IAM Calculation
• Spectrum: Modeling Spectral Irradiance
• End-to-end system modeling: (none yet, but I'd like to see a few examples of complete ModelChain workflows in here)
• ...

edit: moved Modeling with interval averages from solar position to transposition