Rearrange user guide files into subfolders

[RDaxini]

• Closes Suggestion: reorganise user guide folder with subfolders #2368
• I am familiar with the contributing guidelines
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

[echedey-ls]

I'm afraid the changes are not that straight forward: the user guide cannot be seen now.
There are a lot of warnings in the docs build logs related to the new paths of the files: https://app.readthedocs.org/projects/pvlib-python/builds/27514320/

Attention to [...] installation.rst:136: WARNING: image file not readable: user_guide/_images/clonebutton.png
You may need to change the relative path of this image too.

(and the error reported in #2244 (comment) is also in the log)

[RDaxini]

@echedey-ls thanks, my bad, I didn't mean to mark it as ready for review as I hadn't gotten round to checking the build myself first. Sorry about that

[echedey-ls]

Looks similar to the previous docs, good job. Below, two typos with the :caption: in the main index.

[RDaxini]

Why does the section navigation pane on the left disappear when entering one of the modeling topics items? :S No such issue when entering items from the other subsections

[kandersolar]

I'm not sure, but it is suspect to define redundant toctrees in user_guide/index.rst and user_guide/XX/index.rst. I think the toctree in user_guide/index.rst should have only three entries: getting_started/index, extras/index etc.

[RDaxini]

I think the toctree in user_guide/index.rst should have only three entries: getting_started/index, extras/index etc.

That's what I tried originally (commit f18d138, build #27526199) but still no luck

I can still go back to that format though to avoid the errors about index.rst files not being included in any toctree
Not sure what to do about the section navigation pane issue though

[RDaxini]

I think the toctree in user_guide/index.rst should have only three entries: getting_started/index, extras/index etc.

That's what I tried originally (commit f18d138, build #27526199) but still no luck

I can still go back to that format though to avoid the errors about index.rst files not being included in any toctree Not sure what to do about the section navigation pane issue though

Edit: forgot to mention that by doing this (e.g. getting_started/index) we also end up with a double subsection menu in the navigation pane. Saw this earlier but just double checked again with the latest commits. Getting started -> getting started dropdown -> topics, instead of just getting started -> topics (always open, no dropdowns)

[kandersolar]

we also end up with a double subsection menu in the navigation pane

Bother. It makes sense though. I suppose we could remove the :caption: titles and let sphinx handle it.

@RDaxini since these changes still needs some tweaks, I'm going to retag this PR for 0.12.1.

[RDaxini]

we also end up with a double subsection menu in the navigation pane

Bother. It makes sense though. I suppose we could remove the :caption: titles and let sphinx handle it.

Removing the :caption: ends up removing those sections in the navigation pane (local build image below)
Matching the order in which the subsections are listed in the main and subsection index.rst files (029a11e) fixes the disappearing section navigation pane though EDIT: still disappearing on the first subsection (PVSystem), but working fine on the other subsections...

[kandersolar]

I think we can get rid of these sub-level index.rst files, right? They don't contribute to the docs, and they're causing build warnings.

[kandersolar]

@RDaxini I'm not following your last comment (that screenshot is of the example gallery rather than the user guide).

Anyway it seems like the docs build well now! I don't see any disappearing subsections. The only issue I see are some build warnings, mentioned in the comment below above.

[RDaxini]

Should be good to go now

[kandersolar]

LGTM! Thanks @RDaxini

[RDaxini]

Thanks all for reviewing