📝 Add github permalinks to docs (#3)

* 📝 Add github permalinks to docs

* 📝 Re-use release variable instead of __version__

* 🐛 Fix CI/rtd which does site-packages install

docs/source/conf.py

@@ -9,7 +9,8 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # 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 sys
 from pathlib import Path
 
@@ -19,7 +20,7 @@
 
 current_dir = Path(__file__).parent.absolute()
 base_dir = current_dir.parents[1]
-code_dir = base_dir / "src" / "mapply"
+code_dir = base_dir / "src"
 
 sys.path.insert(0, str(code_dir))
 
@@ -51,6 +52,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
     "sphinx.ext.napoleon",
+    "sphinx.ext.linkcode",
 ]
 autodoc_typehints = "description"
 
@@ -79,6 +81,9 @@
 # html_static_path = ["_static"]
 
 
+# -- Options for sphinx.ext.autodoc ------------------------------------------
+
+
 def run_apidoc(_):
     exclude = []
 
@@ -101,3 +106,70 @@ def run_apidoc(_):
 
 def setup(app):
     app.connect("builder-inited", run_apidoc)
+
+
+# -- Options for sphinx.ext.linkcode -----------------------------------------
+
+
+def linkcode_resolve(  # noqa:CCR001
+    domain,
+    info,
+    blob_url="https://github.com/ddelange/mapply/blob",
+    default_branch="master",  # branch used for untagged 'latest' builds on readthedocs
+    tag_prefix="",  # could be for instance "v" depending on tagging convention
+):
+    """Determine a GitHub permalink (with line numbers) for a Python object. Adapted from https://github.com/numpy/numpy/blob/v1.19.4/doc/source/conf.py."""
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            obj = getattr(obj, part)
+        except Exception:
+            return None
+
+    # strip decorators, which would resolve to the source of the decorator
+    # possibly an upstream bug in getsourcefile, bpo-1764286
+    obj = inspect.unwrap(obj)
+
+    try:
+        sourcefile = inspect.getsourcefile(obj)
+    except Exception:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except Exception:
+        linespec = ""
+    else:
+        linespec = f"#L{lineno}-L{lineno + len(source) - 1}"
+
+    try:
+        # editable install
+        relsourcefile = Path(sourcefile).relative_to(base_dir)
+    except ValueError as exc:
+        # site-packages
+        if "site-packages/" not in sourcefile:
+            raise RuntimeError(
+                "Expected a pip install -e, or install to site-packages"
+            ) from exc
+
+        relsourcefile = (code_dir / sourcefile.split("site-packages/")[-1]).relative_to(
+            base_dir
+        )
+
+    if "dev" in release:
+        # setuptools_scm (setup.py) appends a dev identifier to __version__ if there are
+        # commits since last tag. For readthedocs, this is only the case when building
+        # 'latest' that is newer than 'stable', for which the default_branch is assumed.
+        return f"{blob_url}/{default_branch}/{relsourcefile}{linespec}"
+    else:
+        return f"{blob_url}/{tag_prefix}{release}/{relsourcefile}{linespec}"