Open RDaxini opened 1 week ago
Is there an automated tool we could use perhaps with bibtex file?
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.
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:
Anyway, +1 from my side to move to this extension progressively.
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.
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:
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... [1] custom text whatever we want
approach, right? Is it possible to mix the two bibliography methods in a single docstring?show_references()
or something to get the list. Just brainstorming, not saying I think we should do these in pvlib.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.
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.
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.
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.
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.
+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.
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.
restructuring first
yes
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
.py
file could be updatedThe 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. :)