diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index c6e4e36346..0415acb644 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_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 + 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_source_files_base_url() # Edit on GitHub source code links + + def make_github_url(file_name): """ Generate the appropriate GH link for a given docs page. This function @@ -463,11 +501,8 @@ 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" """ - - 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] diff --git a/docs/sphinx/source/whatsnew/v0.12.1.rst b/docs/sphinx/source/whatsnew/v0.12.1.rst index 223c037f75..89bd2d2071 100644 --- a/docs/sphinx/source/whatsnew/v0.12.1.rst +++ b/docs/sphinx/source/whatsnew/v0.12.1.rst @@ -55,6 +55,8 @@ Documentation (:issue:`2333`, :pull:`2437`) * Update references in :py:func:`~pvlib.iotools.get_cams` and :py:func:`~pvlib.iotools.read_cams` (:issue:`2427`, :pull:`2457`) +* 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 ~~~~~~~~~~~~ @@ -78,6 +80,7 @@ Contributors * Kevin Anderson (:ghuser:`kandersolar`) * Will Holmgren (:ghuser:`wholmgren`) * Muhammad Rebaal (:ghuser:`Muhammad-Rebaal`) +* Echedey Luis (:ghuser:`echedey-ls`) * omahs (:ghuser:`omahs`) * Adam R. Jensen (:ghuser:`AdamRJensen`) * Marion Schroedter-Homscheidt (:ghuser:`mschroedter`)