From 476213ede1b1ceb1426d97522170c2428906d53d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Echedey=20Luis=20=C3=81lvarez?= <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 22 May 2025 00:43:37 +0100 Subject: [PATCH 1/5] Update conf.py --- docs/sphinx/source/conf.py | 41 +++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index c6e4e36346..d68e47b583 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -412,6 +412,41 @@ def setup(app): # https://gist.github.com/flying-sheep/b65875c0ce965fbdd1d9e5d0b9851ef1 +# select correct base URL depending on the build system context +def get_base_url(): + """ + Get the base URL for the source code to generate links to GitHub source. + If the build is on ReadTheDocs and it's a stable version, use the + versioned link. If it's a latest version, use the main link. + + For other builds (e.g. pull requests), use the main link. + Local builds will also use the main link. + + Resulting base URL should end with a trailing slash. + + See https://docs.readthedocs.com/platform/stable/reference/environment-variables.html + """ # noqa: E501 + repo_url = os.environ.get( + "READTHEDOCS_GIT_CLONE_URL", + default="https://github.com/pvlib/pvlib-python", + ) + READTHEDOCS_ENV = os.environ.get("READTHEDOCS", None) == "True" + READTHEDOCS_VERSION = os.environ.get("READTHEDOCS_VERSION", None) + READTHEDOCS_GIT_IDENTIFIER = os.environ.get( + "READTHEDOCS_GIT_IDENTIFIER", None + ) + if READTHEDOCS_ENV: # Building docs on ReadTheDocs + if READTHEDOCS_VERSION == "latest": # latest version, commited to main + repo_url += "/blob/main/" + elif READTHEDOCS_VERSION == "stable": # stable version, has a tag + repo_url += f"/blob/{READTHEDOCS_GIT_IDENTIFIER}/" + else: # pull request, user and branch are unknown so use main + repo_url += "/blob/main/" + else: # Local build + repo_url += "/blob/main/" # can't tell where to point to + return repo_url + + def get_obj_module(qualname): """ Get a module/class/attribute and its original module by qualname. @@ -456,6 +491,9 @@ def get_linenos(obj): return start, start + len(lines) - 1 +URL_BASE = get_base_url() # Source code URL for Edit on GitHub links + + def make_github_url(file_name): """ Generate the appropriate GH link for a given docs page. This function @@ -465,9 +503,6 @@ def make_github_url(file_name): sphinx theme has a built-in `file_name` variable that looks like "/docs/sphinx/source/api.rst" or "generated/pvlib.atmosphere.alt2pres.rst" """ - - URL_BASE = "https://github.com/pvlib/pvlib-python/blob/main/" - # is it a gallery page? if any(d in file_name for d in sphinx_gallery_conf['gallery_dirs']): example_folder = file_name.split("/")[-2] From b095a32bb4d1b10338ffae79fee05c72ed9a16db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Echedey=20Luis=20=C3=81lvarez?= <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 22 May 2025 00:50:03 +0100 Subject: [PATCH 2/5] was this a typo? --- docs/sphinx/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index d68e47b583..61f0eda144 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -501,7 +501,7 @@ def make_github_url(file_name): The target URL is built differently based on the type of page. The pydata sphinx theme has a built-in `file_name` variable that looks like - "/docs/sphinx/source/api.rst" or "generated/pvlib.atmosphere.alt2pres.rst" + "docs/sphinx/source/api.rst" or "generated/pvlib.atmosphere.alt2pres.rst" """ # is it a gallery page? if any(d in file_name for d in sphinx_gallery_conf['gallery_dirs']): From d1fbfff545e2103fa50dffb0db25cf12498f7ed5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Echedey=20Luis=20=C3=81lvarez?= <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 22 May 2025 01:04:20 +0100 Subject: [PATCH 3/5] rename function --- docs/sphinx/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 61f0eda144..0415acb644 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -413,7 +413,7 @@ def setup(app): # select correct base URL depending on the build system context -def get_base_url(): +def get_source_files_base_url(): """ Get the base URL for the source code to generate links to GitHub source. If the build is on ReadTheDocs and it's a stable version, use the @@ -491,7 +491,7 @@ def get_linenos(obj): return start, start + len(lines) - 1 -URL_BASE = get_base_url() # Source code URL for Edit on GitHub links +URL_BASE = get_source_files_base_url() # Edit on GitHub source code links def make_github_url(file_name): From 4622e3ecaaead28ade877cdbb684ed2859c1ef43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Echedey=20Luis=20=C3=81lvarez?= <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 22 May 2025 01:04:28 +0100 Subject: [PATCH 4/5] whatsnew entry --- docs/sphinx/source/whatsnew/v0.12.1.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sphinx/source/whatsnew/v0.12.1.rst b/docs/sphinx/source/whatsnew/v0.12.1.rst index 6152f03c7e..839049f469 100644 --- a/docs/sphinx/source/whatsnew/v0.12.1.rst +++ b/docs/sphinx/source/whatsnew/v0.12.1.rst @@ -43,6 +43,7 @@ Documentation :py:func:`~pvlib.pvsystem.sapm` (:issue:`2392`, :pull:`2435`) * Update references in :py:func`~pvlib.irradiance.get_extra_radiation` (:issue:`2333`, :pull:`2347`) +* Fix ``Edit on GitHub`` links in stable documentation right sidebar do not refer to the exact version of the repository at the time of the build. (:issue:`2456`, :pull:`2460`) Requirements ~~~~~~~~~~~~ @@ -66,3 +67,4 @@ Contributors * Kevin Anderson (:ghuser:`kandersolar`) * Will Holmgren (:ghuser:`wholmgren`) * Muhammad Rebaal (:ghuser:`Muhammad-Rebaal`) +* Echedey Luis (:ghuser:`echedey-ls`) From 387b08419eb60e0bab4e1287d0ae64395e9e10ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Echedey=20Luis=20=C3=81lvarez?= <80125792+echedey-ls@users.noreply.github.com> Date: Thu, 22 May 2025 12:33:58 +0100 Subject: [PATCH 5/5] copilot review kevin dont get me wrong, i'm not an ai fanboy --- docs/sphinx/source/whatsnew/v0.12.1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/whatsnew/v0.12.1.rst b/docs/sphinx/source/whatsnew/v0.12.1.rst index 24ada2d213..44b0cf8f4c 100644 --- a/docs/sphinx/source/whatsnew/v0.12.1.rst +++ b/docs/sphinx/source/whatsnew/v0.12.1.rst @@ -43,7 +43,7 @@ Documentation :py:func:`~pvlib.pvsystem.sapm` (:issue:`2392`, :pull:`2435`) * Update references in :py:func`~pvlib.irradiance.get_extra_radiation` (:issue:`2333`, :pull:`2347`) -* Fix ``Edit on GitHub`` links in stable documentation right sidebar do not refer to the exact version of the repository at the time of the build. (:issue:`2456`, :pull:`2460`) +* Fix ``Edit on GitHub`` links in stable documentation so they point to the tagged repository version matching the build environment (e.g., v0.12.0). (:issue:`2456`, :pull:`2460`) Requirements ~~~~~~~~~~~~