Repository navigation
DOC: add reference callouts and enable footnote warnings - #2927
WhatIsAPM1989 wants to merge 3 commits into
Conversation
Connect existing references to the descriptions of the corresponding models, correct spectral model citations, and remove the global suppression of unreferenced-footnote warnings. No calculation code changes. Assisted-by: Codex (GPT-6)
Move callouts into extended descriptions so autosummary tables retain citation-free summaries and do not produce unknown-target errors. Assisted-by: Codex (GPT-6)
Assisted-by: Codex (GPT-6)
Hey @WhatIsAPM1989! 🎉Thanks for opening your first pull request! We appreciate your If AI is used for any portion of this PR, you must vet the content Finally, be sure the PR description includes the PR |
|
@WhatIsAPM1989 your AI PR stated that the draft version was reviewed by the agent and was awaiting your review. You marked the draft PR as ready for review now, but didn't remove that statement. You (or the AI?) also incorrectly ticked the maintainer item off the checklist when no labels or milestones have been added. Do not be offended if I am mistaken but this seems (at least to me) that no human oversight is present, and the AI attestation from the human contributor is intentionally false, so I am closing this PR. This PR could potentially be reopened if you can you confirm you reviewed this yourself, explain what that entailed, and fix the aforementioned issues. @pvlib/pvlib-maintainer please provide generalized guidance whether I should close PRs of this nature or offer guiding comments only. I did not review the diff given the contradictions in the PR; I am not convinced the guidelines are or will be followed. Feel free to re-open. |
|
My intention was to use my otherwise unused AI tokens to make a useful open-source contribution. I found pvlib through TOA (Tokens of Appreciation), which suggested this project and issue. The changes were prepared and reviewed by AI agents, but I did not personally review the diff or validate the technical content. I marked the PR ready without completing that human review, so the AI attestation and maintainer checkbox were incorrect. I apologize for the misleading checklist and description, and for taking up your time. |
|
Interesting. pvlib is # 4 on the “Climate” list here: https://donatetokens.org/#projects |
I'm in favor of coding agents, I use them myself. I support others using them too of course. However, I wonder how many people see the irony in wasting energy and water resources on AI slop framed as "donating" to a climate-related software tool 🫠 |
Do you call that AI slop because this code is really bad, or you call that any AI generated PR? |
|
Thanks for engaging. Your questions are fair.
Neither. It is because the guidelines weren't followed and no human oversight was provided at the initial opening, which is one of those guidelines. Lack of compliance in this basic way makes it difficult for reviewers to be convinced that the contributor will engage with the review process if they put the time into reviewing.
If you are willing to engage with the process, we absolutely welcome your contribution. If this is the case, let us know, fix the checklist, and I (and I'm sure others) will happily review your contribution:) |
|
Thank you for clarifying, and for being willing to review the contribution. I respect your guidelines. I don’t currently understand the technical material well enough to independently review and validate the changes myself, so I can’t provide the level of human oversight you require. Please leave the PR closed. I appreciate your time and the constructive explanation. |
Feel free to close PRs if you think the burden on maintainers will exceed the value added to the library. We can always re-open if we disagree. In this case: someone has to check each of these new callouts against the paper being cited; that would take hours. And, its not clear that the added callouts actually improve the documentation. #837 is still open, but the path to closing is incremental and human-based, not an AI agent blazing through the codebase. @WhatIsAPM1989 thanks for your well-intentioned PR. It sounds like you appreciate the human burden for reviewing AI-generated code changes. |
|
Just to add on top of spot-on contributions of @RDaxini and @cwhanse to the conversation, I think that AI is shifting the community to be less of a community. LLM arbitration gets most of the attention, while (finding/training) potential long-term contributors/maintainers and prioritizing the needs of the project are shifted. I rather have an active community than a clean issues tab. AI still lacks decision-making capabilities. Thank you @WhatIsAPM1989 for understanding. |
Very relevant observation. And this isn't a question of how good AI is. (Full disclosure: my age is above average.) |
I totally agree and in fact wrote nearly identical wording in my notes this morning. Trying to keep up with these PRs is burning me out. Maybe other reviewers are feeling similarly? What do people think about contacting the owner of donatetokens.org (and any other such sites) and asking for pvlib to be removed from their list? |
I need more than two accounts to add more hearts!
Here, I agree with what I think @adriesse is getting at,
even if AI could make great decisions, where does that get us? I like the "(almost) always... by humans for humans" idea [1]. Maybe I'm overthinking it... (not sure if I'm older than average, but I probably use LLMs less than average) [1] https://groups.google.com/g/pvlib-python/c/DvdBCYRi-bg/m/QsMkgSp7AAAJ |
That's part of why I searched out and then posted the link above. Not a maintainer, but I fully support that idea. (I think someone needs a twitter account to contact them??) |
Me also. But the github for that website is only two weeks old, so delisting may help but not dam up the flood of PRs. |
|
I just looked again and it seems pvlib has already been removed. 🤷 |
|
My guess WhatIsAPM1989 is associated with that website |
|
I recommend that we all go through Github issues board and close anything that's not actionable. Especially issues that require some experience in solar or pvlib. If none of us have taken the time to address the issue after all these years then is it really that important? Guessing no. Or one of us can chime in and say "I'm going to reopen this along with a PR". I'd recommend that anyone that's already familiar with pvlib should just open a draft PR instead of an issue. In general I think that we should encourage people in the PV community to just submit PRs. If people feel like they need a discussion first then open a discussion thread. Maybe I should have done one of those things for this comment... maybe one of you will do it! I am totally in support of saying that pvlib is developed by humans for humans. But "by humans" means humans in the loop of AI development, especially when it comes to deciding what to build. I suspect we mostly agree on that given our acceptance of the AI checkbox and its language. And "for humans" also includes humans setting their agents upon some task either with the express instruction to use pvlib or just figure it out and they happen to choose pvlib for reasons like it's well documented, popular, and has a good api (parts of pvlib do, parts don't). So I don't think it's at all reasonable in 2026 to say that, going forward, pvlib should almost always or even mostly be implemented by humans for humans. I hope that distinction is clear. But I am not sure that we're in agreement on it. |
No I am not... |
|
Well, I guess the definitions of “by” and “for” are important and maybe subjective. But keeping a human very engaged on the “by” end seems important for a number of reasons, and maybe “for” doesn’t matter as much. My opinion is that it should be for humans first, and I guess if it’s also LLM/agent-friendly, that’s fine (maybe good/great). I’m guessing that in many cases, better for AI also means better for humans. |
Sorry but this seems like an inappropriate solution to me. The main objective would be to avoid triggering or tempting an AI-agent? There must be a better way. |
I think what I was trying to get at was that I see myself as a member of and contributor to a community more than a submitter of PR's. I have nothing against members of the community using AI tools to help the community. As I ponder what I've just written, it occurs to me that access to these AI tools, especially the better ones, is far from free and open and universal... |
This is reminding me of a discussion that occurred at the OSS Summit in August, I think during @cwhanse's presentation. Assuming some people want their agents to spam repos with issues and PRs to boost their credibility/CV*, if we change the workflow to put more emphasis on discussions instead of issues, doesn't that just mean that the discussions will eventually be spammed by agents? We might be simply relocating the problem. I half-joked at the summit that we could require hand-written letters sent to Cliff's mailbox before opening a PR, but then eventually he'd just get physical spam (which an agent could probably send via something like https://www.handwrytten.com/).
Where would that leave bug reports that don't need to be "discussed"? I opened plenty of those before I was confident/knowledgeable enough to open a PR. * to be clear, this is not what appears to have happened with this PR, which happened to spark this great discussion... |
I entirely agree and certainly didn't mean to suggest that this is no longer valuable. I'm not contributing many PRs these days! From what I can tell, today's agents and harnesses largely ignore discussions. It's certainly possible that discussions will also become an AI wasteland and this is futile. In any case, it's never a bad idea to revisit older issues that we created and see if they really still matter. I only did that for issues that I created and only meant to suggest that people do that for issues that they created. Though I invite you to close anything that I created that you would prefer to see closed. As for alternatives, I've looked into the github project controls and not found anything useful. I'd be happy for others to propose better ideas. Seems that we're all burned out on the status quo.
Maybe I misunderstood but those sound like good issues for random people and their AI agents. If it's really that straightforward then I'd like to think we just push the merge button and move on. Like it or not, there may be be fewer and fewer people in that position as they'll have the agent that just does it all for them. |
Yeah, I had that thought. But as @adriesse pointed out, not everyone has access to these tools, and maybe we don't want to limit their ability to submit a bug report? And/or they aren't comfortable enough with the tools to guide them in submitting a non-problematic PR? I'm thinking "out loud" here, maybe these aren't legitimate concerns. |
|
Anyone could still create an issue. If it's actionable with little discussion then we leave it be. If it needs discussion then we push the "convert to discussion" button. |
Ah, I misunderstood. |
|
(Trigger warning: wall of text ahead, I promise I won't write another one for a day or two)
Yeah man. Even thou I mostly stick to the technical part of the PRs (I seldomly review the scientific references, and I hardly debate whether scientifically the feature adds or not and how it fits in the scientific modelling workflow). I can't imagine how much time and effort you actually invest behind the scenes testing, keeping PRs up-to-date, considering they have been reviewed thoroughly enough and assuming the team consensus is positive when there's notable silence. A few of you have the merit of breaking the ice in slop PRs, moderating what deserves further review or not for the rest of the team. I'm actually 95% of the time ok with what I'm doing now. Just using my spare time without much (if any significant) responsibility. It may be a good time to re-evaluate tasks and involvement of each one. Maybe talk about that in a quarterly meeting? It's been some time since I last got an update on them (2025-05-23) - which I understand. Honestly IDK if I would now find the energy to deal with meetings. But I encourage this "bandwidth" check conversation. Note that if it's too much work to do now by the active team, maybe we should try to lessen the work. Maybe switch to another platform (I don't know if main GitLab, Codeberg, or other git hosting platforms have the same AI slop issue), maybe change the rate of releases, maybe require reviews for preset time windows as a gauge of interest. I don't know what else can be done. I haven't seen any open source project tackle this issue successfully.
Honestly I don't even know if I agree or not. You can use the back of a drill as a hammer too. But if the task doesn't require a hammer the result won't be any good. I see some people using AI when searching for a string of text would have been better. I see many other people keeping AI comments in the code extremely verbose that don't provide any extra information, context or traceability. I see too much people not really understanding the design criteria behind each line of code. I see an absurd amount of people ignoring how quality even looks like. See this PR for example. I don't give a shit that footnotes 1 and 2 are the references used. I already know that by looking at the section name. I want to know where do the equations come from, where a validation was made, what the conditions of the experimental data are, or where are other coefficients to pick from. I mean, tolerating AI is tolerating content that doesn't follow a rational thinking and therefore it does not leave a fingerprint of that thinking in the PRs. I do use it, but for just-me-and-my-code projects. But believe me I don't miss a single line without reviewing it. Regarding pvlib, I won't risk introducing low-quality code, incomplete changes or becoming stupider (for now).
+1. If there's an API it will be exploited sooner or later. Months ago I read in a comment, in YouTube or Instagram, that an LLM is no different from the smarphone's autocomplete (with steroids) in the keyboard, and that kept within my head. I think it sums pretty much my feelings against AI. |
Connect the existing bibliography entries to the corresponding model descriptions and remove the global suppression of unreferenced-footnote warnings. This also fixes the spectral-model citation mapping and adds the missing callouts in four gallery examples.
Validation: the HTML documentation build with gallery execution disabled (
-D plot_gallery=0) reduces unreferenced-footnote warnings from 99 to 0. The existing SPA autosummary andsingleaxismarkup diagnostics also reproduce on cleanmain, alongside offline inventory/example warnings. The CI-style Flake8 diff check passes, an AST comparison confirms that executable Python is unchanged, and all 702 rendered footnote links resolve to local targets.The earlier claim on #837 dates from January 2020; no current claim or competing PR was found.
docs/sphinx/source/whatsnew.AI disclosure: prepared autonomously with Codex (GPT-6) via TOA on behalf of @WhatIsAPM1989, self-reviewed by the agent. This draft awaits the contributor's review and AI-material attestation.