ENH - link shortening support for codeberg, forgejo, gitea

Signed-off-by: Martin Matous <[email protected]>

Author: mmatous

docs/user_guide/theme-elements.md

@@ -238,6 +238,37 @@ For example:
 
 There are a variety of link targets supported, here's a table for reference:
 
+**Codeberg**
+
+- `https://codeberg.org`: https://codeberg.org
+- `https://codeberg.org/c-org`: https://codeberg.org/c-org
+- `https://codeberg.org/c-org/c-repo`: https://codeberg.org/c-org/c-repo
+- `https://codeberg.org/c-org/c-repo/issues/375583`: https://codeberg.org/c-org/c-repo/issues/375583
+- `https://codeberg.org/c-org/c-repo/pulls/1012`: https://codeberg.org/c-org/c-repo/pulls/1012
+
+**Forgejo**
+
+Since self-hosted Forgejo instances can't be easily identified, only links specified
+in `forgejo_url` (links to project's own forge) or domains containing "forgejo"
+leading to issues, pull requests or projects are shortened.
+
+- `https://my-forgejo.org`: https://my-forgejo.org
+- `https://forgejo.my.org/forgejo-org/forgejo`: https://my-forgejo.org/forgejo-org/forgejo/pulls
+- `https://my-forgejo.com/forgejo-org/forgejo/issues/375583`: https://my-forgejo.org/forgejo-org/forgejo/issues/375583
+- `https://my.forgejo.org/forgejo-org/forgejo/pulls/1012`: https://my.forgejo.org/forgejo-org/forgejo/pulls/1012
+
+**Gitea**
+
+`https://gitea.com` is always identified, while the same rules in place for Forgejo
+apply to self-hosted instances.
+
+- `https://gitea.com`: https://gitea.com
+- `https://my-gitea.com`: https://my-gitea.com
+- `https://gitea.com/gitea-org`: https://gitea.com/gitea-org
+- `https://gitea.com/gitea-org/gitea`: https://gitea.com/gitea-org/gitea
+- `https://my-gitea.com/gitea-org/gitea/issues/375583`: https://my-gitea.com/gitea-org/gitea/issues/375583
+- `https://gitea.my.com/gitea-org/gitea/pulls/1012`: https://gitea.my.com/gitea-org/gitea/pulls/1012
+
 **GitHub**
 
 - `https://github.com`: https://github.com

src/pydata_sphinx_theme/assets/styles/base/_base.scss

@@ -46,16 +46,48 @@ a {
     user-select: none;
   }
 
-  // set up a icon next to the shorten links from github and gitlab
+  // set up an icon next to the shortened links from forges
+  &.codeberg,
+  &.forgejo,
+  &.gitea,
   &.github,
   &.gitlab {
     &::before {
       color: var(--pst-color-text-muted);
-      font: var(--fa-font-brands);
       margin-right: 0.25rem;
     }
   }
 
+  &.codeberg,
+  &.forgejo,
+  &.gitea {
+    &::before {
+      display: inline-block;
+      vertical-align: -15%;
+      width: calc(var(--pst-font-size-icon) - 0.5rem);
+      height: calc(var(--pst-font-size-icon) - 0.5rem);
+    }
+  }
+
+  &.github,
+  &.gitlab {
+    &::before {
+      font: var(--fa-font-brands);
+    }
+  }
+
+  &.codeberg::before {
+    content: var(--pst-icon-codeberg);
+  }
+
+  &.forgejo::before {
+    content: var(--pst-icon-forgejo);
+  }
+
+  &.gitea::before {
+    content: var(--pst-icon-gitea);
+  }
+
   &.github::before {
     content: var(--pst-icon-github);
   }

src/pydata_sphinx_theme/assets/styles/variables/_icons.scss

@@ -24,6 +24,17 @@ html {
   --pst-icon-bell: "\f0f3"; // fa-solid fa-bell
   --pst-icon-pencil: "\f303"; // fa-solid fa-pencil
 
+  // SVG icons
+  // minified & encoded by SVGOMG 3.0.0 + https://yoksel.github.io/url-encoder/
+  // https://codeberg.org/Codeberg/Design/src/commit/ac514aa9aaa2457d4af3c3e13df3ab136d22a49a/logo/icon/svg/codeberg-logo_icon_blue.svg
+  --pst-icon-codeberg: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' viewBox='0 0 4.233 4.233'%3E%3Cdefs%3E%3ClinearGradient xlink:href='%23a' id='b' x1='42519.285' x2='42575.336' y1='-7078.789' y2='-6966.931' gradientUnits='userSpaceOnUse'/%3E%3ClinearGradient id='a'%3E%3Cstop offset='0' style='stop-color:%232185d0;stop-opacity:0'/%3E%3Cstop offset='.495' style='stop-color:%232185d0;stop-opacity:.30000001'/%3E%3Cstop offset='1' style='stop-color:%232185d0;stop-opacity:.30000001'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath d='M42519.285-7078.79a.76.568 0 0 0-.738.675l33.586 125.888a87.182 87.182 0 0 0 39.381-33.763l-71.565-92.52a.76.568 0 0 0-.664-.28z' style='font-variation-settings:normal;opacity:1;vector-effect:none;fill:url(%23b);fill-opacity:1;stroke:none;stroke-width:3.67846;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:2;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:stroke markers fill;stop-color:%23000;stop-opacity:1' transform='translate(-1030.156 172.97) scale(.02428)'/%3E%3Cpath d='M11249.461-1883.696c-12.74 0-23.067 10.327-23.067 23.067 0 4.333 1.22 8.58 3.522 12.251l19.232-24.863c.138-.18.486-.18.624 0l19.233 24.864a23.068 23.068 0 0 0 3.523-12.252c0-12.74-10.327-23.067-23.067-23.067z' style='opacity:1;fill:%232185d0;fill-opacity:1;stroke-width:17.0055;paint-order:markers fill stroke;stop-color:%23000' transform='translate(-1030.156 172.97) scale(.09176)'/%3E%3C/svg%3E");
+
+  // https://codeberg.org/forgejo/forgejo/src/commit/0ce1f708202c966ea190dc1f91b0d527ceb09c11/assets/logo.svg
+  --pst-icon-forgejo: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 212 212'%3E%3Cstyle%3Ecircle,path%7Bfill:none;stroke:%23000;stroke-width:15%7Dpath%7Bstroke-width:25%7D.orange%7Bstroke:%23f60%7D.red%7Bstroke:%23d40000%7D%3C/style%3E%3Cg transform='translate(6 6)'%3E%3Cpath d='M58 168V70a50 50 0 0 1 50-50h20' class='orange'/%3E%3Cpath d='M58 168v-30a50 50 0 0 1 50-50h20' class='red'/%3E%3Ccircle cx='142' cy='20' r='18' class='orange'/%3E%3Ccircle cx='142' cy='88' r='18' class='red'/%3E%3Ccircle cx='58' cy='180' r='18' class='red'/%3E%3C/g%3E%3C/svg%3E");
+
+  // https://gitea.com/gitea/design/src/commit/4f571b3c617d2330dc066c5f076f62ac84723dd2/logo/logo.svg
+  --pst-icon-gitea: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 640 640'%3E%3Cpath fill='%23fff' d='m395.9 484.2-126.9-61c-12.5-6-17.9-21.2-11.8-33.8l61-126.9c6-12.5 21.2-17.9 33.8-11.8 17.2 8.3 27.1 13 27.1 13l-.1-109.2 16.7-.1.1 117.1s57.4 24.2 83.1 40.1c3.7 2.3 10.2 6.8 12.9 14.4 2.1 6.1 2 13.1-1 19.3l-61 126.9c-6.2 12.7-21.4 18.1-33.9 12z'/%3E%3Cg fill='%23609926'%3E%3Cpath d='M622.7 149.8c-4.1-4.1-9.6-4-9.6-4s-117.2 6.6-177.9 8c-13.3.3-26.5.6-39.6.7v117.2c-5.5-2.6-11.1-5.3-16.6-7.9 0-36.4-.1-109.2-.1-109.2-29 .4-89.2-2.2-89.2-2.2s-141.4-7.1-156.8-8.5c-9.8-.6-22.5-2.1-39 1.5-8.7 1.8-33.5 7.4-53.8 26.9C-4.9 212.4 6.6 276.2 8 285.8c1.7 11.7 6.9 44.2 31.7 72.5 45.8 56.1 144.4 54.8 144.4 54.8s12.1 28.9 30.6 55.5c25 33.1 50.7 58.9 75.7 62 63 0 188.9-.1 188.9-.1s12 .1 28.3-10.3c14-8.5 26.5-23.4 26.5-23.4S547 483 565 451.5c5.5-9.7 10.1-19.1 14.1-28 0 0 55.2-117.1 55.2-231.1-1.1-34.5-9.6-40.6-11.6-42.6zM125.6 353.9c-25.9-8.5-36.9-18.7-36.9-18.7S69.6 321.8 60 295.4c-16.5-44.2-1.4-71.2-1.4-71.2s8.4-22.5 38.5-30c13.8-3.7 31-3.1 31-3.1s7.1 59.4 15.7 94.2c7.2 29.2 24.8 77.7 24.8 77.7s-26.1-3.1-43-9.1zm300.3 107.6s-6.1 14.5-19.6 15.4c-5.8.4-10.3-1.2-10.3-1.2s-.3-.1-5.3-2.1l-112.9-55s-10.9-5.7-12.8-15.6c-2.2-8.1 2.7-18.1 2.7-18.1L322 273s4.8-9.7 12.2-13c.6-.3 2.3-1 4.5-1.5 8.1-2.1 18 2.8 18 2.8L467.4 315s12.6 5.7 15.3 16.2c1.9 7.4-.5 14-1.8 17.2-6.3 15.4-55 113.1-55 113.1z'/%3E%3Cpath d='M326.8 380.1c-8.2.1-15.4 5.8-17.3 13.8-1.9 8 2 16.3 9.1 20 7.7 4 17.5 1.8 22.7-5.4 5.1-7.1 4.3-16.9-1.8-23.1l24-49.1c1.5.1 3.7.2 6.2-.5 4.1-.9 7.1-3.6 7.1-3.6 4.2 1.8 8.6 3.8 13.2 6.1 4.8 2.4 9.3 4.9 13.4 7.3.9.5 1.8 1.1 2.8 1.9 1.6 1.3 3.4 3.1 4.7 5.5 1.9 5.5-1.9 14.9-1.9 14.9-2.3 7.6-18.4 40.6-18.4 40.6-8.1-.2-15.3 5-17.7 12.5-2.6 8.1 1.1 17.3 8.9 21.3 7.8 4 17.4 1.7 22.5-5.3 5-6.8 4.6-16.3-1.1-22.6 1.9-3.7 3.7-7.4 5.6-11.3 5-10.4 13.5-30.4 13.5-30.4.9-1.7 5.7-10.3 2.7-21.3-2.5-11.4-12.6-16.7-12.6-16.7-12.2-7.9-29.2-15.2-29.2-15.2s0-4.1-1.1-7.1c-1.1-3.1-2.8-5.1-3.9-6.3 4.7-9.7 9.4-19.3 14.1-29-4.1-2-8.1-4-12.2-6.1-4.8 9.8-9.7 19.7-14.5 29.5-6.7-.1-12.9 3.5-16.1 9.4-3.4 6.3-2.7 14.1 1.9 19.8l-24.6 50.4z'/%3E%3C/g%3E%3C/svg%3E");
+
   // Bootstrap icons
   --pst-breadcrumb-divider: "\f105";
 }

src/pydata_sphinx_theme/short_link.py

@@ -1,19 +1,20 @@
 """A custom Transform object to shorten github and gitlab links."""
 
-from typing import ClassVar
+from typing import ClassVar, Literal
 from urllib.parse import ParseResult, urlparse, urlunparse
 
 from docutils import nodes
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util.nodes import NodeMatcher
 
-from .utils import traverse_or_findall
+from .utils import get_theme_options_dict, traverse_or_findall
 
 
 class ShortenLinkTransform(SphinxPostTransform):
     """
-    Shorten link when they are coming from github or gitlab and add an extra class to
-    the tag for further styling.
+    Shorten links leading to supported forges.
+    Also attempt to identify self-hosted forge instances.
+    Add an extra class to the tag for further styling.
 
     Before:
         .. code-block:: html
@@ -35,6 +36,8 @@ class ShortenLinkTransform(SphinxPostTransform):
     default_priority = 400
     formats = ("html",)
     supported_platform: ClassVar[dict[str, str]] = {
+        "codeberg.org": "codeberg",
+        "gitea.com": "gitea",
         "github.com": "github",
         "gitlab.com": "gitlab",
     }
@@ -53,10 +56,54 @@ def run(self, **kwargs):
                 uri = urlparse(uri)
                 # only do something if the platform is identified
                 self.platform = self.supported_platform.get(uri.netloc)
+                # or we can make a reasonable guess about self-hosted forges
+                if self.platform is None:
+                    html_theme_options = get_theme_options_dict(self.app)
+                    self.platform = self.identify_selfhosted(uri, html_theme_options)
                 if self.platform is not None:
                     node.attributes["classes"].append(self.platform)
                     node.children[0] = nodes.Text(self.parse_url(uri))
 
+    def identify_selfhosted(
+        self, uri: ParseResult, html_theme_options: dict[str, str]
+    ) -> Literal["forgejo", "gitea", "gitlab"] | None:
+        """Try to identify what self-hosted forge uri leads to (if any).
+
+        Args:
+            uri: the link to the platform content
+            html_theme_options: varia
+
+        Returns:
+            likely platform if one matches, None otherwise
+        """
+        # forge name in authority and known url part in the right place
+        # unreliable but may catch any number of hosts
+        path_parts = uri.path.strip("/").split("/")
+        if len(path_parts) > 2 and path_parts[2] in ("pulls", "issues", "projects"):
+            if "forgejo" in uri.netloc:
+                return "forgejo"
+            elif "gitea" in uri.netloc:
+                return "gitea"
+        if (
+            len(path_parts) > 3
+            and path_parts[2] == "-"
+            and path_parts[3] in ("issues", "merge_requests")
+        ):
+            if "gitlab" in uri.netloc:
+                return "gitlab"
+
+        # url passed in *_url option
+        # will only match project's own forge but that's
+        # likely where most doc links will lead anyway
+        str_url = f"{uri.scheme}://{uri.netloc}"
+        selfhosted = ("forgejo", "gitea", "gitlab")
+        for forge in selfhosted:
+            known_url = html_theme_options.get(f"{forge}_url")
+            if known_url and known_url.startswith(str_url):
+                return forge
+
+        return None
+
     def parse_url(self, uri: ParseResult) -> str:
         """Parse the content of the url with respect to the selected platform.
 
@@ -119,5 +166,14 @@ def parse_url(self, uri: ParseResult) -> str:
                 # for example "<group>/<subgroup1>/<subgroup2>/<repository>"
                 text = uri._replace(netloc="", scheme="")  # remove platform
                 text = urlunparse(text)[1:]  # combine to string and strip leading "/"
+        elif self.platform in ("codeberg", "forgejo", "gitea"):
+            parts = path.rstrip("/").split("/")
+            if len(parts) == 4 and parts[2] in ("issues", "pulls"):
+                text = f"{parts[0]}/{parts[1]}#{parts[3]}"  # element number
+            elif parts == [""]:
+                text = self.platform
+            else:
+                text = uri._replace(netloc="", scheme="")  # remove platform
+                text = urlunparse(text)[1:]  # combine to string and strip leading "/"
 
         return text

tests/sites/base/page1.rst

@@ -5,6 +5,64 @@ Page 1
 
 - https://pydata-sphinx-theme.readthedocs.io/en/latest/
 
+**Codeberg**
+
+.. container:: codeberg-container
+
+    https://codeberg.org
+    https://codeberg.org/codeberg-org
+    https://codeberg.org/codeberg-org/f-repo
+    https://codeberg.org/codeberg-org/f-repo/issues
+    https://codeberg.org/codeberg-org/f-repo/issues/
+    https://codeberg.org/codeberg-org/f-repo/issues/42
+    https://codeberg.org/codeberg-org/f-repo/pulls/
+    https://codeberg.org/codeberg-org/f-repo/pulls/1012
+    https://codeberg.org/codeberg-org/-/projects
+    https://codeberg.org/codeberg-org/-/projects/2
+    https://codeberg.org/codeberg-org/f-repo/projects
+    https://codeberg.org/codeberg-org/f-repo/projects/1
+    https://codeberg.org/codeberg-org/f-repo/link/to/unknown/feature
+    https://codeberg.org/explore/repos
+
+**Forgejo**
+
+.. container:: forgejo-container
+
+    https://my-forgejo.org
+    https://my-forgejo.org/forgejo-org
+    https://my-forgejo.org/forgejo-org/f-repo
+    https://my-forgejo.org/forgejo-org/f-repo/issues
+    https://my-forgejo.org/forgejo-org/f-repo/issues/
+    https://my-forgejo.org/forgejo-org/f-repo/issues/42
+    https://my-forgejo.org/forgejo-org/f-repo/pulls/
+    https://forgejo.my.org/forgejo-org/f-repo/pulls/1012
+    https://forgejo.my.org/forgejo-org/-/projects
+    https://forgejo.my.org/forgejo-org/-/projects/2
+    https://forgejo.my.org/forgejo-org/f-repo/projects
+    https://forgejo.my.org/forgejo-org/f-repo/projects/1
+    https://forgejo.my.org/forgejo-org/f-repo/link/to/unknown/feature
+    https://forgejo.my.org/explore/repos
+
+
+**Gitea**
+
+.. container:: gitea-container
+
+    https://gitea.com
+    https://gitea.com/gitea-org
+    https://gitea.com/gitea-org/g-repo
+    https://gitea.com/gitea-org/g-repo/issues
+    https://gitea.com/gitea-org/g-repo/issues/
+    https://gitea.com/gitea-org/g-repo/issues/42
+    https://gitea.com/gitea-org/g-repo/pulls/
+    https://gitea.com/gitea-org/g-repo/pulls/1012
+    https://gitea.com/gitea-org/-/projects
+    https://gitea.com/gitea-org/-/projects/2
+    https://gitea.com/gitea-org/g-repo/projects
+    https://gitea.com/gitea-org/g-repo/projects/1
+    https://gitea.com/gitea-org/g-repo/link/to/unknown/feature
+    https://gitea.com/explore/repos
+
 **GitHub**
 
 .. container:: github-container

tests/test_build.py

@@ -894,6 +894,19 @@ def test_shorten_link(sphinx_build_factory, file_regression) -> None:
     """Regression test for "edit on <provider>" link shortening."""
     sphinx_build = sphinx_build_factory("base").build()
 
+    codeberg = sphinx_build.html_tree("page1.html").select(".codeberg-container")[0]
+    file_regression.check(
+        codeberg.prettify(), basename="codeberg_links", extension=".html"
+    )
+
+    forgejo = sphinx_build.html_tree("page1.html").select(".forgejo-container")[0]
+    file_regression.check(
+        forgejo.prettify(), basename="forgejo_links", extension=".html"
+    )
+
+    gitea = sphinx_build.html_tree("page1.html").select(".gitea-container")[0]
+    file_regression.check(gitea.prettify(), basename="gitea_links", extension=".html")
+
     github = sphinx_build.html_tree("page1.html").select(".github-container")[0]
     file_regression.check(github.prettify(), basename="github_links", extension=".html")
 

tests/test_build/codeberg_links.html

@@ -0,0 +1,46 @@
+<div class="codeberg-container docutils container">
+ <p>
+  <a class="codeberg reference external" href="https://codeberg.org">
+   codeberg
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org">
+   codeberg-org
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo">
+   codeberg-org/f-repo
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo/issues">
+   codeberg-org/f-repo/issues
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo/issues/">
+   codeberg-org/f-repo/issues/
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo/issues/42">
+   codeberg-org/f-repo#42
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo/pulls/">
+   codeberg-org/f-repo/pulls/
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo/pulls/1012">
+   codeberg-org/f-repo#1012
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/-/projects">
+   codeberg-org/-/projects
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/-/projects/2">
+   codeberg-org/-/projects/2
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo/projects">
+   codeberg-org/f-repo/projects
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo/projects/1">
+   codeberg-org/f-repo/projects/1
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/codeberg-org/f-repo/link/to/unknown/feature">
+   codeberg-org/f-repo/link/to/unknown/feature
+  </a>
+  <a class="codeberg reference external" href="https://codeberg.org/explore/repos">
+   explore/repos
+  </a>
+ </p>
+</div>

tests/test_build/forgejo_links.html

@@ -0,0 +1,46 @@
+<div class="forgejo-container docutils container">
+ <p>
+  <a class="reference external" href="https://my-forgejo.org">
+   https://my-forgejo.org
+  </a>
+  <a class="reference external" href="https://my-forgejo.org/forgejo-org">
+   https://my-forgejo.org/forgejo-org
+  </a>
+  <a class="reference external" href="https://my-forgejo.org/forgejo-org/f-repo">
+   https://my-forgejo.org/forgejo-org/f-repo
+  </a>
+  <a class="forgejo reference external" href="https://my-forgejo.org/forgejo-org/f-repo/issues">
+   forgejo-org/f-repo/issues
+  </a>
+  <a class="forgejo reference external" href="https://my-forgejo.org/forgejo-org/f-repo/issues/">
+   forgejo-org/f-repo/issues/
+  </a>
+  <a class="forgejo reference external" href="https://my-forgejo.org/forgejo-org/f-repo/issues/42">
+   forgejo-org/f-repo#42
+  </a>
+  <a class="forgejo reference external" href="https://my-forgejo.org/forgejo-org/f-repo/pulls/">
+   forgejo-org/f-repo/pulls/
+  </a>
+  <a class="forgejo reference external" href="https://forgejo.my.org/forgejo-org/f-repo/pulls/1012">
+   forgejo-org/f-repo#1012
+  </a>
+  <a class="forgejo reference external" href="https://forgejo.my.org/forgejo-org/-/projects">
+   forgejo-org/-/projects
+  </a>
+  <a class="forgejo reference external" href="https://forgejo.my.org/forgejo-org/-/projects/2">
+   forgejo-org/-/projects/2
+  </a>
+  <a class="forgejo reference external" href="https://forgejo.my.org/forgejo-org/f-repo/projects">
+   forgejo-org/f-repo/projects
+  </a>
+  <a class="forgejo reference external" href="https://forgejo.my.org/forgejo-org/f-repo/projects/1">
+   forgejo-org/f-repo/projects/1
+  </a>
+  <a class="reference external" href="https://forgejo.my.org/forgejo-org/f-repo/link/to/unknown/feature">
+   https://forgejo.my.org/forgejo-org/f-repo/link/to/unknown/feature
+  </a>
+  <a class="reference external" href="https://forgejo.my.org/explore/repos">
+   https://forgejo.my.org/explore/repos
+  </a>
+ </p>
+</div>