DOC - Add links to source code in GitHub (#22)

* add link to source code

* mitigate impact of jitclasses

* revival

* cleanups

Author: Badr-MOUFAD

doc/conf.py

@@ -19,6 +19,7 @@
 import sphinx_gallery  # noqa
 import sphinx_bootstrap_theme
 from numpydoc import numpydoc, docscrape  # noqa
+from doc.github_link import make_linkcode_resolve
 
 
 # Mathurin: disable agg warnings in doc
@@ -50,6 +51,7 @@
     'sphinx.ext.mathjax',
     'sphinx_gallery.gen_gallery',
     'numpydoc',
+    "sphinx.ext.linkcode",
 ]
 
 # generate autosummary even if no references
@@ -330,6 +332,14 @@
     'sklearn': ('http://scikit-learn.org/stable', None),
 }
 
+# The following is used by sphinx.ext.linkcode to provide links to github
+linkcode_resolve = make_linkcode_resolve(
+    "skglm",
+    "https://github.com/scikit-learn-contrib/"
+    "skglm/blob/{revision}/"
+    "{package}/{path}#L{lineno}",
+)
+
 sphinx_gallery_conf = {
     # 'backreferences_dir': 'gen_modules/backreferences',
     'backreferences_dir': 'generated',

doc/github_link.py

@@ -0,0 +1,83 @@
+# this code is a copy/paste of
+# https://github.com/scikit-learn/scikit-learn/blob/
+# b0b8a39d8bb80611398e4c57895420d5cb1dfe09/doc/sphinxext/github_link.py
+
+from operator import attrgetter
+import inspect
+import subprocess
+import os
+import sys
+from functools import partial
+
+REVISION_CMD = "git rev-parse --short HEAD"
+
+
+def _get_git_revision():
+    try:
+        revision = subprocess.check_output(REVISION_CMD.split()).strip()
+    except (subprocess.CalledProcessError, OSError):
+        print("Failed to execute git to get revision")
+        return None
+    return revision.decode("utf-8")
+
+
+def _linkcode_resolve(domain, info, package, url_fmt, revision):
+    """Determine a link to online source for a class/method/function
+    This is called by sphinx.ext.linkcode
+    An example with a long-untouched module that everyone has
+    >>> _linkcode_resolve('py', {'module': 'tty',
+    ...                          'fullname': 'setraw'},
+    ...                   package='tty',
+    ...                   url_fmt='http://hg.python.org/cpython/file/'
+    ...                           '{revision}/Lib/{package}/{path}#L{lineno}',
+    ...                   revision='xxxx')
+    'http://hg.python.org/cpython/file/xxxx/Lib/tty/tty.py#L18'
+    """
+
+    if revision is None:
+        return
+    if domain not in ("py", "pyx"):
+        return
+    if not info.get("module") or not info.get("fullname"):
+        return
+
+    class_name = info["fullname"].split(".")[0]
+    module = __import__(info["module"], fromlist=[class_name])
+    obj = attrgetter(info["fullname"])(module)
+
+    # Unwrap the object to get the correct source
+    # file in case that is wrapped by a decorator
+    obj = inspect.unwrap(obj)
+
+    try:
+        fn = inspect.getsourcefile(obj)
+    except Exception:
+        fn = None
+    if not fn:
+        try:
+            fn = inspect.getsourcefile(sys.modules[obj.__module__])
+        except Exception:
+            fn = None
+    if not fn:
+        return
+
+    fn = os.path.relpath(fn, start=os.path.dirname(__import__(package).__file__))
+    try:
+        lineno = inspect.getsourcelines(obj)[1]
+    except Exception:
+        lineno = ""
+    return url_fmt.format(revision=revision, package=package, path=fn, lineno=lineno)
+
+
+def make_linkcode_resolve(package, url_fmt):
+    """Returns a linkcode_resolve function for the given URL format
+    revision is a git commit reference (hash or name)
+    package is the name of the root module of the package
+    url_fmt is along the lines of ('https://github.com/USER/PROJECT/'
+                                   'blob/{revision}/{package}/'
+                                   '{path}#L{lineno}')
+    """
+    revision = _get_git_revision()
+    return partial(
+        _linkcode_resolve, revision=revision, package=package, url_fmt=url_fmt
+    )