[docs] Links to GitHub code from the docs 🎉 (asteroid-team#363)

julien-c · Nov 28, 2020 · 5a02a65 · 5a02a65
1 parent 0244c73
commit 5a02a65
Showing 1 changed file with 43 additions and 2 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -30,7 +30,7 @@
 # The short X.Y version
 version = "0.4.0"
 # The full version, including alpha/beta/rc tags
-release = "0.4.0alpha"
+release = "0.4.0rc1"
 
 # -- General configuration ---------------------------------------------------
 
@@ -53,7 +53,7 @@
     # 'sphinxcontrib.fulltoc',  # breaks pytorch-theme with unexpected
     # w argument 'titles_only'
     # We can either use viewcode, which shows source code in the doc page
-    "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
     # Or linkcode to find the corresponding code in github. Start with viewcode
     # 'sphinx.ext.linkcode',
     # 'recommonmark',
@@ -107,6 +107,47 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+
+# Resolve function for the linkcode extension. Now, the source button links
+# to the Github code instead of code in the docs.
+def linkcode_resolve(domain, info):
+    # TODO: handle the release better. Maybe use the versioneer?
+    if domain != "py" or not info["module"]:
+        return None
+    info["module"] = info["module"].replace("asteroid.filterbanks", "asteroid_filterbanks")
+    link_to_afb = "asteroid_filterbanks" in info["module"]
+    repos_name = "asteroid_filterbanks" if link_to_afb else "asteroid"
+
+    def str_from(string, start="asteroid"):
+        return string[string.find(start) :]
+
+    def find_source():
+        import inspect
+
+        # try to find the correct line number, based on code from numpy and lasagne (5 years old)
+        # get(asteroid, engine) -> get(engine, system) -> get(system, engine)
+        obj = sys.modules[info["module"]]
+        for part in info["fullname"].split("."):
+            obj = getattr(obj, part)
+        fn = inspect.getsourcefile(obj)
+        source, lineno = inspect.getsourcelines(obj)
+        return fn, lineno, lineno + len(source) - 1
+
+    filename = info["module"].replace(".", "/")
+    tag = "master" if "dev" in release else ("v" + release)
+
+    if "asteroid_filterbanks" in filename:
+        base_url = "https://github.com/asteroid-team/asteroid-filterbanks/blob/master/%s"
+    else:
+        base_url = f"https://github.com/mpariente/asteroid/blob/{tag}/%s"
+
+    try:
+        file, start, end = find_source()
+    except:
+        return base_url % str_from(filename, start=repos_name)
+    return base_url % str_from(file, start=repos_name) + "#L%d-L%d" % (start, end)
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for