pvlib
Add style guide for references in `contributing/style_guide.rst`
- [X] Closes #2202
- [x] I am familiar with the contributing guidelines
- [ ] Tests added
- [ ] Updates entries in
docs/sphinx/source/referencefor API changes. - [x] Adds description and name entries in the appropriate "what's new" file in
docs/sphinx/source/whatsnewfor 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`). - [x] New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
- [x] Pull request is nearly complete and ready for detailed review.
- [x] Maintainer: Appropriate GitHub Labels (including
remote-data) and Milestone are assigned to the Pull Request and linked Issue.
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
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.
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
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.”
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)
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?
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.
@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 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
@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.
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.