Overhaul of readthedocs documentation

[cwhanse]

It's been a long-standing development goal to overhaul pvlib's documentation, primarily, the organization of pages.

I propose we imitate numpy.org in the hopes that this structure can carry over to pvlib.org when that site is stood up. Mimicking numpy.org, the major headings would be:

• Install. Move content from the current User Guide/Installation)
• Documentation. Subordinate pages would be
  -- Getting Started
  -- User Guide. This is our current user guide which needs front page with an overview of PV modeling, and more logical ordering of the topics. Use the PVPMC figure here?
  -- API Reference. Needs a clean-up and more subheadings.
  -- Contributor’s Guide
• Community. Create a new page, link to Stackoverflow, Googlegroup, pvpmc.org and other resources to get help etc.
• About Us. Move some content from README. Governance goes here.
• News. Current What's New page.
• Contribute. Current Contributing page.

[RDaxini]

Overall I like the proposed structure. A few thoughts:

• Install. Move content from the current User Guide/Installation)

+1 to separating install from the user guide
Perhaps "variables and symbols" could also be moved from the user guide to the documentation section, possibly the "Contributor's guide".

• Contribute.

+1 for a headline Contribute page, and I guess it makes sense to have a separate more detailed guide within the documentation section.

If we do go for this structure of having two contributing-themed sections, I think it's important to have an explicit hyperlink/reference between the two. Unless I missed it, the numpy headline Contribute page doesn't link the guide anywhere. If I was a new user and jumped to their headline "Contribute" page, I don't think I'd easily find the more detailed guide as it is somewhat hidden within the headline documentation page.

I am also in favour of the roadmap idea (#1893)

[echedey-ls]

Linking my own comment for future reference. Relevant content is in how to split the contribute sections, depending on user needs and knowledge. Not a strong opinion, just a casual brainstorm idea:

1. Easy tasks and other great ways to contribute
   • all the great info that already has that section
   • maybe encourage readers to report new scientific models that may be of interest too?
2. Basics of how to edit code publicly through GitHub and make pull requests
   • primer on GitHub, GitHub desktop&git, forking, cloning, editing files, pushing changes, creating PRs
3. Set up the working environment and understand pvlib frameworks
   • recommendations on what python version to use, set up the virtualenv, explain the workflows (how to find the docs, flake8, pytest)
   • explain what is sphinx, pytest, rst; link to useful sites here maybe
4. Add features to pvlib
   1. Admonition on what is eligible to be included in pvlib
   2. Style-guide and mastering docstrings
      • code style
      • Superscripts
      • rST useful links
      • docstring example potentially here
      • recommend figures instead of images (for the captions)
   3. New functional code: add scientific models
      • how to create and document a new function
      • other pieces of code that may need to be updated (__init__.py's, rST indexes for docs)
      • link to testing subsection
   4. Dealing with object-oriented code
      • how to extend the current pvlib classes (what is interesting to add, essentially, and which are the main classes)
      • link to testing subsection
5. testing
   • functional code test strategy, and recommended data sources (excel, other implementations, from published paper)
   • object-oriented code test strategy; mocks & spys
6. (potentially other development frameworks like asv?)

[cwhanse]

Connecting details from other conversations: add a Contact link to the About Us or to the Contributing page. #2210 (comment)