search

pvlib / pvlib-python

A set of documented functions for simulating the performance of photovoltaic energy systems.
https://pvlib-python.readthedocs.io
BSD 3-Clause "New" or "Revised" License
1.21k stars 1.01k forks source link

Update virtual environment guide URL on contributing page #2200

Closed RDaxini closed 2 months ago

RDaxini commented 2 months ago

Original link: https://docs.astropy.org/en/latest/development/workflow/virtual_pythons.html New link: https://astropy-astrofrog.readthedocs.io/en/latest/development/workflow/virtual_pythons.html Could someone confirm the new link here is the correct/intended webpage for the guide?

RDaxini commented 2 months ago

I am wondering whether it might be also be useful to integrate this link, which directs to the pvlib user guide section on virtual environments, into the same sentence?

kandersolar commented 2 months ago

New link: https://astropy-astrofrog.readthedocs.io/en/latest/development/workflow/virtual_pythons.html Could someone confirm the new link here is the correct/intended webpage for the guide?

Based on the URL, this seems to be an "unofficial" set of docs that astrofrog (an astropy developer) has set up. I don't think we should link to it.

How about something like https://learn.scientific-python.org/development/tutorials/dev-environment/ instead? I haven't compared in depth with the previous page, but in general I'd prefer to link to some kind of central resource like scientific-python.org instead of another package's docs.

mikofski commented 2 months ago

No, I would keep the sections separate. Although they are both related to setting up a dev environment for contributing, the 2nd focuses on using conda . I think pvlib needs to have its own help on this that doesn’t depend on a link to another project. There should be links between the two sections tho.

RDaxini commented 2 months ago

No, I would keep the sections separate. Although they are both related to setting up a dev environment for contributing, the 2nd focuses on using conda . I think pvlib needs to have its own help on this that doesn’t depend on a link to another project. There should be links between the two sections tho.

Ah... when I said integrate the link into the sentence, I meant literally only the link --- not bring over the linked section and merge both sections. See b298674 for what I had in mind. Let me know what you think

RDaxini commented 2 months ago

LGTM! I'll leave this open for a few days in case any other ideas pop up.

Actually something I have been thinking about is that there is no obvious point of contact on the contributing page in case someone wants to reach out. What is the best point of contact, is it the Google group? Is there an email address? The Google group is linked in the Easy ways to contribute section, which is good, but perhaps referring to that link (or whatever is the best contact option) somewhere more explicitly as a means of getting in touch with the community for advice/questions about contributing to pvlib specifically might be an improvement.

Another thought, after reading some of the contributing pages on other projects (through the discussion in #2202), I feel like our contributing page would benefit from being broken up into a few pages. These pages would still all be under the same "Contributing" section, but they could be navigated through using the sidebar (like the user guide?) In this way, we could keep the really basic basics one one (the first) page, then move other details such as code style, testing, virtual environments, etc. onto separate pages rather than just separate sections on the same page. I think that this single page in its current form may be overwhelming for new users; it certainly was for me not so many months ago 😅

What do you guys think? These points may be out of scope for this URL update PR (at least the second one is for sure) and may warrant a separate issue for further discussion first. Should I open a new issue for either or both of these points?

cwhanse commented 2 months ago

What is the best point of contact, is it the Google group? Is there an email address?

I would prefer that they open an Issue or Discussion rather than send an email.

cwhanse commented 2 months ago

contributing page would benefit from being broken up into a few pages.

Agree fully.

RDaxini commented 2 months ago

LGTM! I'll leave this open for a few days in case any other ideas pop up.

Actually something I have been thinking about is that there is no obvious point of contact on the contributing page in case someone wants to reach out. What is the best point of contact, is it the Google group? Is there an email address? The Google group is linked in the Easy ways to contribute section, which is good, but perhaps referring to that link (or whatever is the best contact option) somewhere more explicitly as a means of getting in touch with the community for advice/questions about contributing to pvlib specifically might be an improvement.

Another thought, after reading some of the contributing pages on other projects (through the discussion in #2202), I feel like our contributing page would benefit from being broken up into a few pages. These pages would still all be under the same "Contributing" section, but they could be navigated through using the sidebar (like the user guide?) In this way, we could keep the really basic basics one one (the first) page, then move other details such as code style, testing, virtual environments, etc. onto separate pages rather than just separate sections on the same page. I think that this single page in its current form may be overwhelming for new users; it certainly was for me not so many months ago 😅

What do you guys think? These points may be out of scope for this URL update PR (at least the second one is for sure) and may warrant a separate issue for further discussion first. Should I open a new issue for either or both of these points?

These points will be resolved separately now (#2210) so, other than those points, if there's anything else required for this PR then just let me know

kandersolar commented 2 months ago

Thanks @RDaxini!