Add Github source links to generated API documentation (#923)

Fixes #921

Author: chrisrink10

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Other
  * Add REPL documentation module (#205)
  * Add documentation module for Basilisp interfaces (#920)
+ * Add GitHub source links to generated API documentation (#921)
  * Update Sphinx documentation theme (#909)
  * Update documentation to directly reference Python documentation and fix many other minor issues and misspellings (#907, #919)
 

docs/conf.py

@@ -5,7 +5,10 @@
 # This file does only contain a selection of the most common options. For a
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
-
+import os
+import pathlib
+import re
+import sys
 
 # -- Project information -----------------------------------------------------
 
@@ -173,3 +176,32 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
+
+# -- Options for Basilisp's custom linkcode ----------------------------------
+
+_vcs_branch = os.getenv("READTHEDOCS_GIT_IDENTIFIER", "main")
+
+
+def lpy_linkcode_resolve(filename, lines):
+    if not filename:
+        return None
+
+    pth = None
+    for path in sys.path:
+        try:
+            pth = pathlib.Path(filename).relative_to(path)
+        except ValueError:
+            continue
+
+    if pth is None:
+        return None
+
+    line_anchor = ""
+    if lines and (match := re.match(r"(\d+)(?::(\d+))?", lines)) is not None:
+        start_line = match.group(1)
+        if (end_line := match.group(2)) is None:
+            line_anchor = f"#L{start_line}"
+        else:
+            line_anchor = f"#L{start_line}-L{end_line}"
+
+    return f"https://github.com/basilisp-lang/basilisp/blob/{_vcs_branch}/src/{pth}{line_anchor}"

src/basilisp/contrib/sphinx/__init__.py

@@ -1,5 +1,6 @@
 from sphinx.application import Sphinx
 
+from basilisp.contrib.sphinx import linkcode
 from basilisp.contrib.sphinx.autodoc import (
     NamespaceDocumenter,
     ProtocolDocumenter,
@@ -38,5 +39,8 @@ def setup(app: Sphinx) -> None:
     app.add_autodocumenter(TypeDocumenter)
     app.add_autodocumenter(RecordDocumenter)
 
+    app.connect("doctree-read", linkcode.doctree_read)
+    app.add_config_value("lpy_linkcode_resolve", None, "")
+
 
 __all__ = ("setup",)

src/basilisp/contrib/sphinx/autodoc.py

@@ -37,6 +37,7 @@
 # Var metadata used for annotations
 _DOC_KW = kw.keyword("doc")
 _LINE_KW = kw.keyword("line")
+_END_LINE_KW = kw.keyword("end-line")
 _PRIVATE_KW = kw.keyword("private")
 _DYNAMIC_KW = kw.keyword("dynamic")
 _DEPRECATED_KW = kw.keyword("deprecated")
@@ -279,6 +280,13 @@ def add_directive_header(self, sig: str) -> None:
         super().add_directive_header(sig)
 
         if self.object.meta is not None:
+            if (file := self.object.meta.val_at(_FILE_KW)) is not None:
+                self.add_line(f"   :filename: {file}", sourcename)
+            if isinstance(line := self.object.meta.val_at(_LINE_KW), int):
+                if isinstance(end_line := self.object.meta.val_at(_END_LINE_KW), int):
+                    self.add_line(f"   :lines: {line}:{end_line}", sourcename)
+                else:
+                    self.add_line(f"   :lines: {line}", sourcename)
             if self.object.meta.val_at(_DYNAMIC_KW):
                 self.add_line("   :dynamic:", sourcename)
             if self.object.meta.val_at(_DEPRECATED_KW):

src/basilisp/contrib/sphinx/domain.py

@@ -131,6 +131,14 @@ def run(self) -> List[Node]:
 
 
 class BasilispObject(PyObject):  # pylint: disable=abstract-method
+    option_spec: OptionSpec = PyObject.option_spec.copy()
+    option_spec.update(
+        {
+            "filename": directives.unchanged,
+            "lines": directives.unchanged,
+        }
+    )
+
     def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]:
         """Subclasses should implement this themselves."""
         return NotImplemented
@@ -157,9 +165,14 @@ def add_target_and_index(
                     ("single", indextext, node_id, "", None)
                 )
 
+    def _add_source_annotations(self, signode: desc_signature) -> None:
+        for metadata in ("filename", "lines"):
+            if val := self.options.get(metadata):
+                signode[metadata] = val
+
 
 class BasilispVar(BasilispObject):
-    option_spec: OptionSpec = PyObject.option_spec.copy()
+    option_spec: OptionSpec = BasilispObject.option_spec.copy()
     option_spec.update(
         {
             "dynamic": directives.unchanged,
@@ -181,6 +194,8 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]
 
         signode += addnodes.desc_name(sig, sig)
 
+        self._add_source_annotations(signode)
+
         type_ = self.options.get("type")
         if type_:
             signode += addnodes.desc_annotation(type_, "", nodes.Text(": "), type_)
@@ -204,6 +219,8 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]
         if prefix:
             signode += addnodes.desc_annotation(prefix, prefix)
 
+        self._add_source_annotations(signode)
+
         sig_sexp = runtime.first(reader.read_str(sig))
         assert isinstance(sig_sexp, IPersistentList)
         fn_sym = runtime.first(sig_sexp)
@@ -282,6 +299,8 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]
         if prefix:
             signode += addnodes.desc_annotation(prefix, prefix)
 
+        self._add_source_annotations(signode)
+
         signode += addnodes.desc_name(sig, sig)
         return sig, prefix
 

src/basilisp/contrib/sphinx/linkcode.py

@@ -0,0 +1,51 @@
+from typing import Set
+
+from docutils import nodes
+from docutils.nodes import Node
+from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+
+def doctree_read(app: Sphinx, doctree: Node) -> None:
+    env = app.builder.env
+
+    resolve_link = getattr(env.config, "lpy_linkcode_resolve", None)
+    if not callable(resolve_link):
+        logger.warning("No Basilisp linkcode resolver!")
+        return
+
+    for objnode in list(doctree.findall(addnodes.desc)):
+        domain = objnode.get("domain")
+        if domain != "lpy":
+            continue
+
+        uris: Set[str] = set()
+        for signode in objnode:
+            if not isinstance(signode, addnodes.desc_signature):
+                continue
+
+            info = {}
+            for key in ("filename", "lines"):
+                value = signode.get(key)
+                if not value:
+                    value = ""
+                info[key] = value
+
+            if not info or all(not v for v in info.values()):
+                continue
+
+            if not (uri := resolve_link(info.get("filename"), info.get("lines"))):
+                continue
+
+            if uri in uris:
+                continue
+
+            uris.add(uri)
+
+            inline = nodes.inline("", "[source]", classes=["viewcode-link"])
+            onlynode = addnodes.only(expr="html")
+            onlynode += nodes.reference("", "", inline, internal=False, refuri=uri)
+            signode += onlynode  # pylint: disable=redefined-loop-name