[DOC] Fix Edit on Github sidebar link always points to latest commit

[echedey-ls]

• Closes "View on github" links not working #2456
• I am familiar with the contributing guidelines
• [ ] Tests added
• [ ] Updates entries in docs/sphinx/source/reference for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for 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`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

Fix Edit on GitHub links on the right sidebar in stable docs point to latest commit in main, so there is a mismatch if code lines were added/deleted since the last stable release (or a 404 if file got deleted).

The fix consists in switching the base repo url from https://github.com/pvlib/pvlib-python/blob/main to e.g. https://github.com/pvlib/pvlib-python/blob/v0.11.1 depending on the environment variables set by ReadTheDocs at build time. RTD docs on that: https://docs.readthedocs.com/platform/stable/reference/environment-variables.html

Another possibility for "latest" builds is to point to the specific commit, but I doubt that is any useful.

Sidenote for pull requests: it's impossible to link to their repo since user + branch name are unknown by RTD.
Local builds will default to main branch files.

Edit:

Here is my testing strategy, in Python interpreter:

>>> {copy function}
>>> get_source_files_base_url()
'https://github.com/pvlib/pvlib-python/blob/main/'
>>> os.environ["READTHEDOCS"] = "True"     
>>> os.environ["READTHEDOCS_GIT_IDENTIFIER"] = "v0.12.0" 
>>> os.environ["READTHEDOCS_VERSION"] = "stable" 
>>> get_source_files_base_url()
'https://github.com/pvlib/pvlib-python/blob/v0.12.0/'
>>> os.environ["READTHEDOCS_VERSION"] = "latest" 
>>> os.environ["READTHEDOCS_GIT_IDENTIFIER"] = "v0.12.0"
>>> get_source_files_base_url()
'https://github.com/pvlib/pvlib-python/blob/main/'

[Copilot]

Pull Request Overview

This pull request fixes the "Edit on GitHub" link in the stable documentation sidebar so that it correctly points to the repository version corresponding to the build, rather than always defaulting to the main branch.

• Update the whatsnew documentation to describe the link fix.
• Introduce a new helper function get_source_files_base_url() in conf.py to dynamically determine the correct GitHub URL based on RTD environment variables.

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/sphinx/source/whatsnew/v0.12.1.rst	Updates documentation to include the fix for sidebar link accuracy.
docs/sphinx/source/conf.py	Adds a helper function to dynamically generate GitHub URLs for source links.

Comments suppressed due to low confidence (1)

docs/sphinx/source/conf.py:429

• [nitpick] Consider defining the default GitHub repository URL as a constant and factoring out common URL suffixes (such as "/blob/main/") to improve maintainability and ease potential future changes to the URL structure.

repo_url = os.environ.get("READTHEDOCS_GIT_CLONE_URL", default="https://github.com/pvlib/pvlib-python")

[AdamRJensen]

@echedey-ls Do you have an example file/function where this currently is an issue? That seems to be the easiest way to verify that it works, by comparing it to the readthedocs compilation in this PR.

[echedey-ls]

@AdamRJensen you've got a point. Currently PRs are made to point to main, so you will find them exactly the same as a latest build, i.e., correct links except for the files modified by the own PR. I'm afraid this PR review will be open-loop in the strict sense of verifying. The most we can check is how it gets built by defining our local environment variables, by mocking them.

I can't make up the PR correct url (username + branch name) cause RTD is unaware of that info of PRs (GitHub permissions thing). That's what they call external.

[kandersolar]

I agree testing this is not straightforward. It looks right to me, and it sounds like @echedey-ls has done about as much local testing as is possible here, so I'm inclined to merge it and come back to verify that it worked after the next release.

Nice job @echedey-ls!