From 30d33fa23a57214a80e6450e5bc74ae8deb137e1 Mon Sep 17 00:00:00 2001
From: Russell Bryant <rbryant@redhat.com>
Date: Tue, 26 Nov 2024 08:33:36 -0500
Subject: [PATCH] [Doc] Add github links for source code references

Previously, the use of `sphinx.ext.viewcode` generated new pages that
included the raw source code. This change adds the
`sphinx.ext.linkcode` extension, which allows defining a custom method
for generating source code URLs given a code reference. This now
includes links to the appropriate file and line number on github for
code references.

For now I left the `viewcode` extension in place. The result is that
code references now have 2 `[source]` links - one for the copy of the
source in the docs, and one to github. If the github links seem to
work well enough, we can drop `viewcode` later.

Signed-off-by: Russell Bryant <rbryant@redhat.com>
---
 docs/source/conf.py | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 96ad9a4c26b09..822b6a8a76bd1 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -10,6 +10,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
+import inspect
 import logging
 import os
 import sys
@@ -34,6 +35,7 @@
 extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "sphinx.ext.autodoc",
@@ -94,6 +96,25 @@ def setup(app):
     generate_examples()
 
 
+def linkcode_resolve(domain, info):
+    if domain != 'py':
+        return None
+    if not info['module']:
+        return None
+    filename = info['module'].replace('.', '/')
+    module = info['module']
+    try:
+        obj = sys.modules[module]
+        for part in info['fullname'].split('.'):
+            obj = getattr(obj, part)
+        lineno = inspect.getsourcelines(obj)[1]
+        filename = (inspect.getsourcefile(obj)
+                    or f"{filename}.py").split("vllm/", 1)[1]
+        return f"https://github.com/vllm-project/vllm/blob/main/{filename}#L{lineno}"
+    except Exception:
+        return f"https://github.com/vllm-project/vllm/blob/main/{filename}.py"
+
+
 # Mock out external dependencies here, otherwise the autodoc pages may be blank.
 autodoc_mock_imports = [
     "compressed_tensors",