From 01afeddd51c34c8f482a43b2a75745fbab024760 Mon Sep 17 00:00:00 2001
From: Vaibhav Naik <naikvaib@amazon.com>
Date: Sun, 20 Sep 2026 11:22:10 -0700
Subject: [PATCH] docs: link reference API docs back to GitHub source

Replace sphinx.ext.viewcode with sphinx.ext.linkcode and a custom
linkcode_resolve() in docs/conf.py. viewcode only rendered a local copy
of the source inside the docs site; linkcode points each object's
"[source]" link directly at its file/line on
github.com/apache/hamilton, pinned to the release tag when building
from a tag and to the exact commit otherwise so line numbers stay in
sync.

Verified with a local sphinx-build: the StrictIndexTypePandasDataFrameResult
entry cited in the issue now links to
github.com/apache/hamilton/blob/<sha>/hamilton/base.py#L306, the correct
line.

Fixes #572
---
 docs/conf.py | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index dded9aff4..09f035468 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -15,6 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
+import inspect
 import os
 import re
 import subprocess
@@ -22,6 +23,7 @@
 
 # required to get reference documentation to be built
 sys.path.insert(0, os.path.abspath(".."))
+REPO_ROOT = os.path.abspath("..")
 
 apache_footer = """
 <div class="apache-footer">
@@ -72,7 +74,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
     "myst_nb",
     "sphinx_llms_txt",
     "sphinx_sitemap",
@@ -127,3 +129,55 @@
     html_baseurl = "https://hamilton.staged.apache.org/"
 html_extra_path = ["robots.txt"]
 # ---
+
+# for the linkcode extension ---
+# Adds a "[source]" link to each documented object in the API reference that
+# points directly at the corresponding file/line on GitHub (see
+# https://github.com/apache/hamilton/issues/572). When building from a
+# tagged release, link to that tag; otherwise link to the exact commit so
+# line numbers always match the rendered source.
+if re.match(r"^apache-hamilton-(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$", current_tag):
+    linkcode_revision = current_tag
+else:
+    try:
+        linkcode_revision = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()
+    except subprocess.CalledProcessError:
+        linkcode_revision = "main"
+
+
+def linkcode_resolve(domain, info):
+    """Map a documented Python object to its source URL on GitHub.
+
+    Called by sphinx.ext.linkcode for every object in the API reference.
+    """
+    if domain != "py" or not info["module"]:
+        return None
+
+    obj = sys.modules.get(info["module"])
+    for part in info["fullname"].split("."):
+        if obj is None:
+            return None
+        obj = getattr(obj, part, None)
+    if obj is None:
+        return None
+
+    # Unwrap decorators/properties/etc. to get to the underlying function
+    # or class so we point at its actual definition.
+    obj = inspect.unwrap(getattr(obj, "__func__", obj))
+
+    try:
+        filename = inspect.getsourcefile(obj)
+        _, lineno = inspect.getsourcelines(obj)
+    except (TypeError, OSError):
+        return None
+    if not filename:
+        return None
+
+    relative_path = os.path.relpath(filename, start=REPO_ROOT).replace(os.sep, "/")
+    if relative_path.startswith(".."):
+        # Object is defined outside the Hamilton repo (e.g. a third-party
+        # base class) -- nothing sensible to link to.
+        return None
+
+    return f"https://github.com/apache/hamilton/blob/{linkcode_revision}/{relative_path}#L{lineno}"
+# ---