Split contributing.rst

[RDaxini]

• Relates to Split the contributing page #2210
• 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.

Save for a few minor edits such as section order, section headings, and section labels, this PR does not make any substantial revisions to the main text of the contributing page. The purpose of this PR is to split the page. There are ongoing discussions about revising the main text and/or creating new sections, which will be handled separately. Somewhat related: #2202 #2205 #2067 #2081

[RDaxini]

I feel like just "style guide" would be a simpler title but then "building the documentation" doesn't really fit in as well. Suggestions? Is this fine as it is?

[echedey-ls]

Writing code and documentation
Mastering code and docs
Nailing code and docs
Bilingual on code and docs (jk)
Code and documentation

[echedey-ls]

Firstly, nice job Dax and thanks for putting effort into this.
Second, somewhere it was commented (by you IIRC) that a contact note to ask for help would be good, I think we can add that in this PR.
Third, citation style recommendation can be put somewhere in this docs (#2202)

And lastly, I can't help but share my usual wall of text. First disclaimer, I don't mind doing that in a separate PR if consensus is achieved.

Consider the introduction is on the landing/index page of the contributing chapter.

What I have in mind is focusing on the contributor needs depending on experience and what it wants to do, by breaking the docs into the following sections:

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?)

[echedey-ls]

Writing code and documentation
Mastering code and docs
Nailing code and docs
Bilingual on code and docs (jk)
Code and documentation

[echedey-ls]

What about moving the introduction to this place and guide which place is the best for the user? Expecting other people to weight in, I don't dislike how it is now either. In the big wall of the review I share how I would re-distribute the documentation.

[RDaxini]

@echedey-ls thanks for your suggestions. Just personally, I think it would be more manageable from a discussion, development, and reviewing perspective if we first split what we already have into broadly agreed chunks, and then progressively improve each section through revisions or adding new sections/text. I think rewriting the entire contributing page would be too much in a single PR.

somewhere it was commented (by you IIRC) that a contact note to ask for help would be good, I think we can add that in this PR. Third, citation style recommendation can be put somewhere in this docs (#2202)

Yes correct, so I have begun drafting/building locally but following the suggestion above (and what I believe was also suggested in the associated issues) I think it might be easier if we split the page first, then I will open a PR for these aspects. You can open a separate one too, for example if you have ideas for this:

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

I think that alone would be a substantial PR, but still be easier to discuss and review as a single change rather than alongside multiple new pages/text. Linking to this pvlib page might help for that subject btw, personally I found the screenshots and code snippets helpful when setting up not so long ago.

Just my thoughts anyway. I am still learning about the optimal PR scope.

[echedey-ls]

@RDaxini I'm super okay with that, thanks for explaining in depth your PRs procedure. Consider this PR approved from my side. Also, I ran the spell checker and "oveview" is the only warning.

[cwhanse]

I like the split of the material and the new index. As long as that is the scope of this PR, I agree, this is close to ready for merge.

[kandersolar]

This looks good to me, with one exception: it seems like the example gallery section got dropped. Was that intentional?

[RDaxini]

Was that intentional?

Ah no definitely not! My bad. Reinstated in the last commit

[kandersolar]

As @RDaxini suggested, let's view this PR (reorganization existing material) as the first step of a longer-term evolution of the Contributing section. With that in mind, I'll go ahead and merge this, and I look forward to follow-ups for further improvements :)