docs: use iternal _linkcode_resolve (#263)

docs/source/conf.py

@@ -5,16 +5,17 @@
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
 import glob
-import inspect
 import os
 import re
-import sys
-from typing import List, Optional
+from typing import List
 
 import lightning_utilities
 import pt_lightning_sphinx_theme
 from lightning_utilities.docs import adjust_linked_external_docs, fetch_external_assets
 
+# This function is used to populate the (source) links in the API
+from lightning_utilities.docs.formatting import _linkcode_resolve
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -296,41 +297,10 @@ def _package_list_from_file(file: str) -> List[str]:
 
 
 # Resolve function
-# This function is used to populate the (source) links in the API
 def linkcode_resolve(domain, info):
-    def find_source() -> Optional[str]:
-        # try to find the file and line number, based on code from numpy:
-        # https://github.com/numpy/numpy/blob/master/doc/source/conf.py#L286
-        obj = sys.modules[info["module"]]
-        for part in info["fullname"].split("."):
-            obj = getattr(obj, part)
-        fname = inspect.getsourcefile(obj)
-        # https://github.com/rtfd/readthedocs.org/issues/5735
-        if any(s in fname for s in ("readthedocs", "rtfd", "checkouts")):
-            # /home/docs/checkouts/readthedocs.org/user_builds/pytorch_lightning/checkouts/
-            #  devel/pytorch_lightning/utilities/cls_experiment.py#L26-L176
-            path_top = os.path.abspath(os.path.join("..", "..", ".."))
-            fname = os.path.relpath(fname, start=path_top)
-        else:
-            # Local build, imitate master
-            fname = "main/" + os.path.relpath(fname, start=os.path.abspath(".."))
-        source, lineno = inspect.getsourcelines(obj)
-        return fname, lineno, lineno + len(source) - 1
-
-    if domain != "py" or not info["module"]:
-        return None
-    try:
-        filename = "%s#L%d-L%d" % find_source()
-    except Exception:
-        filename = info["module"].replace(".", "/") + ".py"
-    # import subprocess
-    # tag = subprocess.Popen(['git', 'rev-parse', 'HEAD'], stdout=subprocess.PIPE,
-    #                        universal_newlines=True).communicate()[0][:-1]
-    branch = filename.split("/")[0]
-    # do mapping from latest tags to main
-    branch = {"latest": "main", "stable": "main"}.get(branch, branch)
-    filename = "/".join([branch] + filename.split("/")[1:])
-    return f"https://github.com/{github_user}/{github_repo}/blob/{filename}"
+    return _linkcode_resolve(
+        domain, info, github_user=github_user, github_repo=github_repo, main_branch="main", stable_branch="main"
+    )
 
 
 autosummary_generate = True

src/lightning_utilities/docs/formatting.py

@@ -33,7 +33,14 @@ def _transform_changelog(path_in: str, path_out: str) -> None:
         fp.writelines(chlog_lines)
 
 
-def _linkcode_resolve(domain: str, github_user: str, github_repo: str, info: dict) -> str:
+def _linkcode_resolve(
+    domain: str,
+    info: dict,
+    github_user: str,
+    github_repo: str,
+    main_branch: str = "master",
+    stable_branch: str = "release/stable",
+) -> str:
     def find_source() -> Tuple[str, int, int]:
         # try to find the file and line number, based on code from numpy:
         # https://github.com/numpy/numpy/blob/master/doc/source/conf.py#L286
@@ -49,7 +56,7 @@ def find_source() -> Tuple[str, int, int]:
             fname = str(os.path.relpath(fname, start=path_top))
         else:
             # Local build, imitate master
-            fname = f'master/{os.path.relpath(fname, start=os.path.abspath(".."))}'
+            fname = f'{main_branch}/{os.path.relpath(fname, start=os.path.abspath(".."))}'
         source, line_start = inspect.getsourcelines(obj)
         return fname, line_start, line_start + len(source) - 1
 
@@ -64,7 +71,7 @@ def find_source() -> Tuple[str, int, int]:
     #                        universal_newlines=True).communicate()[0][:-1]
     branch = filename.split("/")[0]
     # do mapping from latest tags to master
-    branch = {"latest": "master", "stable": "master"}.get(branch, branch)
+    branch = {"latest": main_branch, "stable": stable_branch}.get(branch, branch)
     filename = "/".join([branch] + filename.split("/")[1:])
     return f"https://github.com/{github_user}/{github_repo}/blob/{filename}"