Restructure the user guide with subsections

[RDaxini]

--edit-- see discussion below, the original suggestion of a new page has evolved into breaking up the user guide into subsections.

Is your feature request related to a problem? Please describe.
Some sections in the user guide don't really fit appropriately there, for example the single diode section. This section feels more educational and general, while still framed in the context of using pvlib.

Describe the solution you'd like
Create a "Learning" main header section (same level as user guide, example gallery, etc.)
Purpose of distinct sections:
Learning: educational content, including general theory, but still in the context of using pvlib / pvlib-python where explanations could be framed around particular pvlib-python functions and functionality. This section could inspire the creation of more educational content in future.
User guide: set up and installation of pvlib-python.

Transfer to the learning section:
Intro Tutorial
PVSystem
ModelChain
Time and time zones
Clear sky
Bifacial modeling
Weather data
Single Diode Equation

Keep in User Guide:
Package Overview
Installation
Variables and Symbols
Frequently Asked Questions

Additional context
In a way, these are all still 'user guide' because they guide users on how to use components of pvlib, so this idea is totally open to other suggestions and/or rejection entirely, but I am interested to hear the thoughts from the community.

[kandersolar]

I think I am not in favor of the proposal as currently written. Our current User Guide seems (to me) similar in scope to those of other projects (in particular, projects with good docs that we might want to emulate):

• SciPy: https://docs.scipy.org/doc/scipy/tutorial/index.html
• NumPy: https://numpy.org/doc/stable/user/index.html
• Astropy: https://docs.astropy.org/en/stable/index_user_docs.html

So I don't think I'm in favor of splitting off some pages into a new Learning section alongside the current User Guide.

However, I do like what NumPy and Astropy have done with organizing the User Guide into subsections. @RDaxini could we adapt your proposal to use subsections in the User Guide rather than creating a new top-level section?

[RDaxini]

I think I am not in favor of the proposal as currently written. Our current User Guide seems (to me) similar in scope to those of other projects (in particular, projects with good docs that we might want to emulate):

• SciPy: https://docs.scipy.org/doc/scipy/tutorial/index.html
• NumPy: https://numpy.org/doc/stable/user/index.html
• Astropy: https://docs.astropy.org/en/stable/index_user_docs.html

So I don't think I'm in favor of splitting off some pages into a new Learning section alongside the current User Guide.

However, I do like what NumPy and Astropy have done with organizing the User Guide into subsections. @RDaxini could we adapt your proposal to use subsections in the User Guide rather than creating a new top-level section?

Fair comment, good suggestion. I'll work up a draft structure for user guide subsections later and, if approved, I will just work it into the existing PR (#2310)
Anyone feel free to suggest a structure too if you like

[RDaxini]

I think a modified version of the numpy.org structure would serve us well here:

Getting started
Package Overview
Installation
Intro Tutorial
Advanced usage
ModelChain
Time and time zones
Clear sky
Bifacial modeling
Weather data
Single Diode Equation
Extras
Variables and Symbols
Frequently Asked Questions

[RDaxini]

Should I add an empty section for model comparison tables (#2329)?
Could be empty or just include a message to say that some comparison tables are on the way

[echedey-ls]

I would leave that out until they are done, or partially done at least. It doesn't add much value to see a "tables on the way, please come back in a few months to see if this has changed!". When they get added, it's better to announce on the whatsnew and that's it.

[RDaxini]

I'm working on the spectral corrections one currently, but was not sure where to put the file in the repository in order to open a PR. What do you think?

[cwhanse]

I'd create the section when you add the first comparison.

[echedey-ls]

I'm working on the spectral corrections one currently, but was not sure where to put the file in the repository in order to open a PR. What do you think?

Uh, legitimate question. I suppose user_guide is the place I would look for it if I had to edit something there.