Support specifying source URLs per directory

Author: oprypin

mkdocstrings/handlers/crystal/__init__.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional, Sequence
+from typing import Any, Mapping, Optional, Sequence
 
 from mkdocstrings.handlers.base import BaseHandler
 
@@ -14,9 +14,12 @@ def get_handler(
     theme: str,
     custom_templates: Optional[str] = None,
     crystal_docs_flags: Sequence[str] = (),
+    source_locations: Mapping[str, str] = (),
     **config: Any
 ) -> CrystalHandler:
-    collector = CrystalCollector(crystal_docs_flags=crystal_docs_flags)
+    collector = CrystalCollector(
+        crystal_docs_flags=crystal_docs_flags, source_locations=source_locations
+    )
     renderer = CrystalRenderer("crystal", theme, custom_templates)
     renderer.collector = collector
     return CrystalHandler(collector, renderer)

mkdocstrings/handlers/crystal/collector.py

@@ -1,17 +1,20 @@
 import collections
+import dataclasses
+import functools
 import json
 import logging
+import os
 import re
 import shlex
 import subprocess
-from typing import Any, Callable, Iterable, Iterator, Mapping, Sequence, TypeVar, Union
+from typing import Any, Callable, Iterable, Iterator, List, Mapping, Sequence, TypeVar, Union
 
 import mkdocs.exceptions
 import mkdocs.utils
 from cached_property import cached_property
 from mkdocstrings.handlers.base import BaseCollector, CollectionError
 
-from .items import DocConstant, DocItem, DocMapping, DocMethod, DocModule, DocType
+from .items import DocConstant, DocItem, DocLocation, DocMapping, DocMethod, DocModule, DocType
 
 try:
     from mkdocs.exceptions import PluginError
@@ -25,7 +28,9 @@
 
 
 class CrystalCollector(BaseCollector):
-    def __init__(self, crystal_docs_flags: Sequence[str] = ()):
+    def __init__(
+        self, crystal_docs_flags: Sequence[str] = (), source_locations: Mapping[str, str] = ()
+    ):
         """Create a "collector", reading docs from `crystal doc` in the current directory.
 
         Normally this should not be instantiated.
@@ -40,23 +45,35 @@ def __init__(self, crystal_docs_flags: Sequence[str] = ()):
             "--format=json",
             "--project-name=",
             "--project-version=",
-            "--source-refname=master",
-            *crystal_docs_flags,
         ]
+        if source_locations:
+            command.append("--source-refname=master")
+        command += crystal_docs_flags
         log.debug("Running `%s`", " ".join(shlex.quote(arg) for arg in command))
 
         self._proc = subprocess.Popen(command, stdout=subprocess.PIPE)
         self._collected = collections.Counter()
 
+        # For unambiguous prefix match: add trailing slash, sort by longest path first.
+        self._source_locations = sorted(
+            (
+                _SourceDestination(os.path.relpath(k) + os.sep, source_locations[k])
+                for k in source_locations
+            ),
+            key=lambda d: -d.src_path.count("/"),
+        )
+
     # pytype: disable=bad-return-type
     @cached_property
-    def root(self) -> DocModule:
+    def root(self) -> "DocRoot":
         """The top-level namespace, represented as a fake module."""
         try:
             with self._proc:
                 data = json.load(self._proc.stdout)
             data["program"]["full_name"] = ""
-            return DocModule(data["program"], None, None)
+            root = DocRoot(data["program"], None, None)
+            root.source_locations = self._source_locations
+            return root
         finally:
             if self._proc.returncode:
                 cmd = " ".join(shlex.quote(arg) for arg in self._proc.args)
@@ -104,6 +121,56 @@ def teardown(self):
                 log.debug(f"These types were never put into the documentation: {not_collected}")
 
 
+@dataclasses.dataclass
+class _SourceDestination:
+    src_path: str
+    dest_url: str
+
+    def substitute(self, location: DocLocation) -> str:
+        data = {"file": location.filename[len(self.src_path) :], "line": location.line}
+        try:
+            return self.dest_url.format_map(collections.ChainMap(data, self))  # type: ignore
+        except KeyError as e:
+            raise PluginError(
+                f"The source_locations template {self.dest_url!r} did not resolve correctly: {e}"
+            )
+
+    def __getitem__(self, key):
+        try:
+            return getattr(self, key)
+        except AttributeError as e:
+            raise KeyError(str(e))
+
+    @property
+    def shard_version(self):
+        return self._shard_version(os.path.dirname(self.src_path))
+
+    @classmethod
+    @functools.lru_cache(maxsize=None)
+    def _shard_version(cls, path: str):
+        file_path = os.path.join(path, "shard.yml")
+        if os.path.isfile(file_path):
+            with open(file_path, "rb") as f:
+                m = re.search(rb"^version: *([\S+]+)", f.read(), flags=re.MULTILINE)
+            if not m:
+                raise PluginError(f"`version:` not found in {file_path!r}")
+            return m[1].decode()
+        if not path:
+            raise PluginError(f"'shard.yml' not found anywhere above {path!r}")
+        return cls._shard_version(os.path.dirname(path))
+
+
+class DocRoot(DocModule):
+    source_locations: List[_SourceDestination]
+
+    def update_url(self, location: DocLocation) -> DocLocation:
+        for dest in self.source_locations:
+            if (location.filename or "").startswith(dest.src_path):
+                location.url = dest.substitute(location)
+                break
+        return location
+
+
 class DocView:
     def __init__(self, item: DocItem, config: Mapping[str, Any]):
         self.item = item

mkdocstrings/handlers/crystal/crystal_html.py

@@ -1,7 +1,7 @@
 import collections
 import html.parser
 import io
-from typing import Callable, Sequence, Tuple
+from typing import Callable, List, Sequence, Tuple
 
 from markupsafe import Markup, escape
 

mkdocstrings/handlers/crystal/items.py

@@ -230,7 +230,7 @@ def including_types(self) -> Sequence[DocPath]:
     def locations(self) -> Sequence[DocLocation]:
         """The [code locations][mkdocstrings.handlers.crystal.items.DocLocation] over which the definitions of this type span."""
         return [
-            DocLocation(loc["filename"], loc["line_number"], loc["url"])
+            self.root.update_url(DocLocation(loc["filename"], loc["line_number"], loc["url"]))
             for loc in self.data["locations"]
         ]
 
@@ -361,15 +361,17 @@ def location(self) -> Optional[DocLocation]:
         try:
             loc = self.data["location"]
         except KeyError:
-            m = re.fullmatch(
-                r".+?/(?:blob|tree)/[^/]+/(.+)#L(\d+)", self.data.get("source_link") or ""
+            loc = None
+            url = self.data.get("source_link")
+            if url:
+                regex = r"(?P<url>.+?/(?:blob|tree)/[^/]+/(?P<filename>.+)#L(?P<line>\d+))"
+                m = re.fullmatch(regex, url)
+                if m:
+                    loc = m.groupdict()
+        if loc:
+            return self.root.update_url(
+                DocLocation(loc["filename"], loc["line_number"], loc["url"])
             )
-            if m:
-                filename, line = m.groups()
-                return DocLocation(filename, line, self.data.get("source_link"))
-        else:
-            if loc:
-                return DocLocation(loc["filename"], loc["line_number"], loc["url"])
 
 
 class DocInstanceMethod(DocMethod):