Add style guide for references in contributing/style_guide.rst

[RDaxini]

• Partially addresses Standard citation style across docs #2202
• I am familiar with the contributing guidelines
• Tests added
• Updates entries in docs/sphinx/source/reference for API changes.
• 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.

[RDaxini]

Questions:
Too long?
More (variety of) example reference types? So far there's the general format for a journal paper, and two examples: journal paper and conference paper
Is it okay to link to a pdf? the pdf was found here

[cwhanse]

Questions: Too long?

No, but a bit wordy in places. I can edit if you'd like.

More (variety of) example reference types?

Yes. I think add a book or book chapter, and a technical report from some lab.

Is it okay to link to a pdf?

I don't see why not.

[RDaxini]

Questions: Too long?

No, but a bit wordy in places. I can edit if you'd like.

Sure, please go ahead

More (variety of) example reference types?

Yes. I think add a book or book chapter, and a technical report from some lab.

Okay will do

[AdamRJensen]

I think we should encourage users not to format it manually, but perhaps use something like this: https://citation.crosscite.org/

Also, the DOI should be required if there is one.

Last, might be a good idea to link to the official IEEE description: https://journals.ieeeauthorcenter.ieee.org/wp-content/uploads/sites/7/IEEE_Reference_Guide.pdf

The official guide (above) states the following, which we should abide by:

IEEE publications must list names of all authors, up to six names. If there are more than six names listed, use the primary author’s name followed by “et al.”

[RDaxini]

I think we should encourage users not to format it manually, but perhaps use something like this: https://citation.crosscite.org/

Do we want pvlib to endorse one particular citation generator though...? I think most people would be aware of such sites and just go ahead and use one themselves if they want to.

Also, the DOI should be required if there is one.

Already included, see line 85

Last, might be a good idea to link to the official IEEE description: https://journals.ieeeauthorcenter.ieee.org/wp-content/uploads/sites/7/IEEE_Reference_Guide.pdf

Already included, see line 78 in the original, 77 since the last commit

The official guide (above) states the following, which we should abide by:

IEEE publications must list names of all authors, up to six names. If there are more than six names listed, use the primary author’s name followed by “et al.”

Have now added it in (line 81)

[kandersolar]

This is OK with me

[echedey-ls]

I feel like so many details aren't necessary. In fact, so many details on how IEEE work may encourage contributors to manually type the citations. But I can live with that.

Do we want pvlib to endorse one particular citation generator though...?

I'd say we don't want to, but citing "Use of a citation generator is recommended" at least somewhere would be nice. Whether or not to provide a link... dunno. I wouldn't put it just as there are plenty of them.

In addition, maybe add Zotero, other bib managers or the published paper webpage as sources to get the IEEE citation from.

LGTM nevertheless, this section would definitely be remembered for whoever reads it!

[AdamRJensen]

On a couple of recent PRs to another repo I've been using the IEEE citation format... and I really dislike how the first name initial comes first. It seems that most pvlib functions already are using a somewhat fairly consistent format - anyone know what that is?

[cwhanse]

It seems that most pvlib functions already are using a somewhat fairly consistent format - anyone know what that is?

Likely, just imitating other references. There hasn't been a citation style specified or requested before.

[RDaxini]

@AdamRJensen I also think the initial/name order is a slightly odd, it's not what I am used to anyway, but it's not a dealbreaker for me. I think IEEE is still a good choice. Is there another style you'd recommend?

[mikofski]

I feel like so many details aren't necessary. In fact, so many details on how IEEE work may encourage contributors to manually type the citations. But I can live with that.

Do we want pvlib to endorse one particular citation generator though...?

I'd say we don't want to, but citing "Use of a citation generator is recommended" at least somewhere would be nice. Whether or not to provide a link... dunno. I wouldn't put it just as there are plenty of them.

In addition, maybe add Zotero, other bib managers or the published paper webpage as sources to get the IEEE citation from.

LGTM nevertheless, this section would definitely be remembered for whoever reads it!

What would be cool is a Zotero group or library that we could share with pvlib users

[echedey-ls]

What would be cool is a Zotero group or library that we could share with pvlib users

@mikofski I'm completely ignorant on that feature of Zotero, but the bibtex file with references in pvlib would be super for that? I mean, centralized in the repo so nobody ever forgets about updating it, in the same PRs that get accepted, and for those non-Zotero users a webpage with all the references to find if a paper is or not relevant in pvlib / a model is a good candidate.

[AdamRJensen]

@AdamRJensen I also think the initial/name order is a slightly odd, it's not what I am used to anyway, but it's not a dealbreaker for me. I think IEEE is still a good choice. Is there another style you'd recommend?

I would vote for the APA style. Here's an example:

IEEE Style:
C. Gueymard, "Analysis of monthly average atmospheric precipitable water and turbidity in Canada and northern United States," Solar Energy, vol. 53, no. 1, pp. 57-71, 1994.

APA Style:
Gueymard, C. (1994). Analysis of monthly average atmospheric precipitable water and turbidity in Canada and northern United States. Solar Energy, 53(1), 57-71. DOI

Vote this post up if you agree with APA and vote down if you prefer IEEE.

[cwhanse]

Vote this post up if you agree with APA and vote down if you prefer IEEE.

Personally, I think the APA style is easier to read. But I'm voting for IEEE because 1) IEEE publishes the many of the references cited, 2) IEEE lets one export the citation but only in the IEEE format. If we choose APA, then I need to edit the citation rather than just copy/paste.

[AdamRJensen]

This is a great addition, very helpful!

@RDaxini thumb up this post and I'll merge this PR in a couple of days.