Standard citation style across docs

[RDaxini]

Is your feature request related to a problem? Please describe.
There is a mix of citation styles currently used in the documentation, both between pages and sometimes on the same page.

quick example:
pvlib.atmosphere.get_relative_airmass
Authors: full name (first+last), and first initial then surname
External links: some with DOI, some for which a DOI exists but is not included (e.g. ref 9).
Misc.: References in the list aren't always linked to something in the text.

Comparing with another page, e.g. pvlib.irradiance.get_ground_diffuse, the naming style is last name then first name initial.

There are also differences in other aspects of the style e.g. page/volume numbers, whether a DOI is included, etc.

---

Describe the solution you'd like

1. Agree on a style
2. Add a section to the user guide and/or contributing guide advising users / potential contributors of the adopted referencing style, and additional suggestions such as to include a DOI if one is available, link reference to something in the text, etc.
3. Future PRs would adopt the agreed style, and old docs could be updated gradually in a few ways:
   3.1- Good first issue PRs for new contributors, e.g. at PVPMC workshops or other tutorials
   3.2- Dedicated PRs for anyone (something to do on those long-haul flights, right...)
   3.3- As existing functions that already contain citations are updated for whatever other purpose, updates to the references could be included in the same PR
   3.4- As new functions are added to the same packages, references for other functions from the same .py file could be updated

The points in 3. are just ideas/suggestions and I hope we can discuss and decide on the best approach(es) together.

As for 1., I am not an expert on citation styles but I know there are many out there, e.g. IEEE, MLA, APA, Harvard...
We could pick on out of there, or perhaps adopt a hybrid style of our own design, e.g. we like IEEE but prefer to keep the author list to one name + et al. for brevity.

---

Question/suggestion: Is adopting bibtex in the docs technically possible? The formatting could be set centrally and users would only need to update a .bib file somewhere (but we should ensure references still appear on the pages where they are cited, so maybe multiple .bib files would be required)

---

Describe alternatives you've considered
We could just continue without a set style but I think having, or at at least encouraging, a consistent citation style would make it easier for users to understand the citations, locate the sources, and even just make pvlib appear more professional. Maybe there's even be a legal(?)/ethical argument there where we need to ensure citations are up to a certain standard when we are sharing other people's work through pvlib. (not certain about that last one, just a thought)

---

Additional context
Perhaps we could start off with point 1 in the solutions: discuss whether this is a good idea and, if so, discuss what would be a good style to adopt.
If we get that far, I'd certainly be happy to resolve 2., and contribute to 3. :)

[mikofski]

Is there an automated tool we could use perhaps with bibtex file?

[RDaxini]

I think there is a suitable bibtex extension in sphinx that would allow us to include citations in the docs in a similar way to latex.

We would need to add the sphinxcontrib.bibtex extension to conf.py first. Then, I am not 100% sure about the structure and extent of automation we can achieve, but from what I have read so far I think it is possible to have one central .bib file from which we can insert citations into the docstring and automate the creation of the reference list using two methods:
:cite: in the main text, .. bibliography:: to generate the reference list, :cited: to ensure only references cited in that particular function/page docstring are listed.
Or there is :footcite: and .. footbibliography::

Users would just need to update the central .bib file with any new references, existing references can easily be re-cited. Reference list creation would be automated.

Something I have not fully understood yet (still reading...) is whether we need a separate .rst (or other...?) file to generate the reference lists for each function, or a reference section is added into each function's docstring as we currently do.

If bibtex is possible and practical in pvlib then then I think I would vote for this option.

[echedey-ls]

Just made a working example at #2204 ; I couldn't help but try that out, I think I fell in love with that project.

In any case, my only possible dealbreakers are in the current status of sphinxcontrib-bibtex but it seems that:

• Style things can be customized
• Project's development still persists, even thou one of its dependencies seems in low-maintenance mode.
  • https://github.com/mcmtroffaes/sphinxcontrib-bibtex/ is the main repo, aware of low activity at
  • https://bitbucket.org/pybtex-devs/pybtex, with special care to issue https://bitbucket.org/pybtex-devs/pybtex/issues/169/replace-pkg_resources-with
    I find these issues can be bypassed in the medium/long-run if problems arise for Py>=3.12, but that for now it should not be an issue. We are not bumping sphinx versions everyday, right? I would perfectly understand that they are a dealbreaker in the context of maintenance.

Anyway, +1 from my side to move to this extension progressively.

[RDaxini]

Just made a working example at #2204 ; I couldn't help but try that out, I think I fell in love with that project.

Yeah I figured it'd be fun to work on that's why I created the issue haha..

In any case, my only possible dealbreakers are in the current status of sphinxcontrib-bibtex but it seems that:

• Style things can be customized

• Project's development still persists, even thou one of its dependencies seems in low-maintenance mode.

  • https://github.com/mcmtroffaes/sphinxcontrib-bibtex/ is the main repo, aware of low activity at
  • https://bitbucket.org/pybtex-devs/pybtex, with special care to issue https://bitbucket.org/pybtex-devs/pybtex/issues/169/replace-pkg_resources-with
    I find these issues can be bypassed in the medium/long-run if problems arise for Py>=3.12, but that for now it should not be an issue. We are not bumping sphinx versions everyday, right? I would perfectly understand that they are a dealbreaker in the context of maintenance.

Anyway, +1 from my side to move to this extension progressively.

#2204 looks good, but I understand these concerns. I'm interested to hear what others say as I have less experience with long term maintenance and the possible implications these points could have on that.

[kandersolar]

a dealbreaker in the context of maintenance

I haven't looked at the linked issues yet, but it might help to see how other projects do citations. If a bigger project (e.g. scipy, astropy) uses this extension too, we can probably feel a bit better about the long-term outlook of this approach.

Initial reactions to #2204:

• It's a shame for the references to not be shown when viewing docstrings in a python terminal using help or IPython's ?, which is the main way I make use of pvlib's docstrings. Of course I recognize that this use case must be the minority compared with the ReadTheDocs site.
• We should think about "weird" types of citation that might not work well with this particular bibtex/sphinx workflow. I am thinking about websites, technical reports, standards etc. Maybe they work fine here, but it is probably worth verifying it sooner rather than later. In my experience, not all bibtex-based workflows have good support for the more "exotic" types of reference.
• We can still use the current .. [1] custom text whatever we want approach, right? Is it possible to mix the two bibliography methods in a single docstring?
• The bibtex file may get large (1000s of lines) if we migrate most references to it. Is there a logical way that it could be organized into multiple files? My first thought was to divide by pvlib module, but that won't work well since some references get cited in multiple modules. Anyway this doesn't have to get solved now.
• What else do structured references enable? For example we could add a docs page listing all references across pvlib. I can't recall the name, but I remember a python package that automatically keeps track of the references for any function your script uses, and then you can call show_references() or something to get the list. Just brainstorming, not saying I think we should do these in pvlib.

[cwhanse]

My opinion: I favor keeping the implementation of references simple. With just text, there's little that can go wrong :) I'm not opposed to a trial using the more automated reference system for part of pvlib, as @kevinsa5 suggests. A reference manager may make more sense for pvlib.org where we are starting from a blank page.

Regardless, I am in favor of choosing a reference style. We can move towards that style progressively.

[cwhanse]

Looking at #2204, as a code reviewer it would be a minor annoyance to have to look in a second file to find a reference's details.

[RDaxini]

I haven't looked at the linked issues yet, but it might help to see how other projects do citations. If a bigger project (e.g. scipy, astropy) uses this extension too, we can probably feel a bit better about the long-term outlook of this approach.

Looking at some of the astropy functions (random example here) it looks like they just use a text list of references as we have been using. Looks like numpy (see here) just uses a text list too. Not sure about scipy, but at least from how they describe citing wikipedia and adding DOIs on this page, it sounds like that's just a text list as well.

Good points in the rest of the comments from @kandersolar and @cwhanse too.

If we were to stick with a text-based list (sounds like the discussion is leaning this way?) then I think the priority is a clear and standard style guide. It's good to see in the other packages linked above they include such guidance, e.g. including DOI, required information in the citation, etc.

We could:
a) adopt a fixed style that already exists
b) create our own style
c) instruct contributors to include certain information in a citation, with source specific guidance as well (e.g. doi for journal articles), and then let them format their reference as they wish

As far as I could see I think option c) is what the projects linked above do.

As for fixed styles that already exist, just for reference here are a few examples:

IEEE, according to this guide
K. S. Anderson, C. W. Hansen, W. F. Holmgren, A. R. Jensen, M. A. Mikofski, and A. Driesse, “pvlib python: 2023 project update,” Journal of Open Source Software, vol. 8, no. 92, Dec. 2023

MLA (according to Google Scholar)
Anderson, Kevin S., et al. "pvlib python: 2023 project update." Journal of Open Source Software 8.92 (2023): 5994.

APA (according to Google Scholar)
Anderson, K. S., Hansen, C. W., Holmgren, W. F., Jensen, A. R., Mikofski, M. A., & Driesse, A. (2023). pvlib python: 2023 project update. Journal of Open Source Software, 8(92), 5994.

Chicago (according to Google Scholar)
Anderson, Kevin S., Clifford W. Hansen, William F. Holmgren, Adam R. Jensen, Mark A. Mikofski, and Anton Driesse. "pvlib python: 2023 project update." Journal of Open Source Software 8, no. 92 (2023): 5994.

Harvard (according to Google Scholar)
Anderson, K.S., Hansen, C.W., Holmgren, W.F., Jensen, A.R., Mikofski, M.A. and Driesse, A., 2023. pvlib python: 2023 project update. Journal of Open Source Software, 8(92), p.5994.

Vancouver (according to Google Scholar)
Anderson KS, Hansen CW, Holmgren WF, Jensen AR, Mikofski MA, Driesse A. pvlib python: 2023 project update. Journal of Open Source Software. 2023 Dec 22;8(92):5994.

[cwhanse]

I would be OK with c (status quo, mostly) or a. I would soften "a" a bit by recommending but not insisting on a formatting style. My preference would be for IEEE because my guess is that it is more common for solar energy journals and conference proceedings. But that's not a strong preference.

[adriesse]

I would certainly follow an easy-to-find recommendation because it's easier than inventing my own or trying to deduce from the existing ones what might be the best example to follow. We could skip the page numbers perhaps.

[AdamRJensen]

+1 on using an existing format for new functions and gradually updating old functions.

Moving forward, I think we should have a template function that demonstrates how to correctly make citations for journal articles, conference papers, websites, and reports.

[RDaxini]

So in summary of the discussion so far, I think the consensus is to:
a) Stick with text over bibtex
b) Recommend (but not insist on) an existing style, namely IEEE, for new functions
c) Existing functions to be updated over time
d) Add an example

Question: should a section be added to the current contributing page now, or hold off until #2210 is resolved?
I think restructuring first and then following up with a new style guide for code, references, units, etc. would probably be better. I wouldn't be opposed to adding something about reference style into the docs now though.

I think the bibtex discussion is still an interesting one (see #2204, @echedey-ls created a good example) so if anyone is interested in that it might still be worth investigating for its future potential.

[cwhanse]

restructuring first

yes

[RDaxini]

Marking this as closed by #2202
Task 3 in the proposed solution will be addressed slowly over time and can still link back to this issue.