Sphinx SmartLink Role

smartlink.py

from docutils import nodes
from docutils.nodes import Node, system_message
from sphinx.roles import ReferenceRole


class SmartLink(ReferenceRole):
    nodeclass_title_explict = nodes.text
    nodeclass_title_default = nodes.literal

    classes = ["smartlink"]
    title_pattern = "{target}"
    uri_pattern = "{base_uri}{prefix}/{target}"
    base_uri = "https://"
    default_prefix = ""

    def run(self) -> tuple[list[Node], list[system_message]]:
        if self.disabled:
            return self.create_smartlink_disabled()
        else:
            return self.create_smartlink()

    def create_smartlink_disabled(self) -> tuple[list[Node], list[system_message]]:
        node = self.nodeclass_title_default(
            self.rawtext, self.build_title(), classes=self.classes)
        return [node], []

    def create_smartlink(self) -> tuple[list[Node], list[system_message]]:
        refuri = self.build_uri()
        reference = nodes.reference(
            '', '', internal=False, refuri=refuri, classes=self.classes)
        title = self.build_title()
        if self.has_explicit_title:
            reference += self.nodeclass_title_explict(title, title)
        else:
            reference += self.nodeclass_title_default(title, title)

        return [reference], []

    def build_title(self) -> str:
        if self.has_explicit_title:
            return self.title

        __, raw_target = self.get_prefix_target_raw()
        last_only = "~" in raw_target[:2]

        prefix, target = self.get_prefix_target()
        if last_only:
            title = self.title.split("/")[-1]
        title = self.title_pattern.format(
            target=target, prefix=prefix, **self.generate_extra())
        return title

    def build_uri(self) -> str:
        prefix, target = self.get_prefix_target
        extra = self.generate_extra()
        return self.uri_pattern.format(
            base_uri=self.base_uri, prefix=prefix, target=target, **extra)

    def generate_extra(self) -> dict[str, str]:
        return {}

    def get_prefix_target(self) -> tuple[str, str]:
        prefix, target = self.get_prefix_target_raw()
        return prefix.lstrip("!~"), target.lstrip("!~")

    def get_prefix_target_raw(self) -> tuple[str, str]:
        target_parts = self.target.split(':', 1)
        if len(target_parts) == 2:
            prefix = target_parts[0]
            target = target_parts[1]
        else:
            prefix = self.default_prefix
            target = target_parts[0]

        return prefix, target


class GitHubFile(SmartLink):
    classes = SmartLink.classes + ["file", "github-file"]
    uri_pattern = "{base_url}blob/{prefix}/{target}"
    base_uri = SmartLink.base_uri + "github.com/"
    default_prefix = "main"


class CPythonFile(SmartLink):
    classes = GitHubFile.classes + ["cpython-file"]
    base_uri = GitHubFile.base_uri + "python/cpython"