From e786e0da780195b88799ec49590a146f90e40f3c Mon Sep 17 00:00:00 2001 From: Matthew Pitkin Date: Tue, 3 Dec 2024 14:28:25 +0000 Subject: [PATCH 1/7] __init__.py: allow gitlab URL link shortening from non-gitlab.com domains --- src/pydata_sphinx_theme/__init__.py | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 3c613831a..3ea7e75b3 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -276,7 +276,23 @@ def setup(app: Sphinx) -> Dict[str, str]: app.add_html_theme("pydata_sphinx_theme", str(theme_path)) - app.add_post_transform(short_link.ShortenLinkTransform) + if hasattr(app.config, "html_context"): + gitlab_url = app.config.html_context.get("gitlab_url", "") + + if gitlab_url.startswith("https://"): + gitlab_url = {gitlab_url[8:].rstrip("/"): "gitlab"} + elif gitlab_url.startswith("http://"): + gitlab_url = {gitlab_url[7:].rstrip("/"): "gitlab"} + else: + gitlab_url = {} + + class ShortenLinkTransformCustom(short_link.ShortenLinkTransform): + supported_platform = short_link.ShortenLinkTransform.supported_platform + supported_platform.update(gitlab_url) + + app.add_post_transform(ShortenLinkTransformCustom) + else: + app.add_post_transform(short_link.ShortenLinkTransform) app.connect("builder-inited", translator.setup_translators) app.connect("builder-inited", update_config) From 0e435853ae15f8f1483c4970abbd263dffe4a9fd Mon Sep 17 00:00:00 2001 From: Matthew Pitkin Date: Wed, 4 Dec 2024 14:31:59 +0000 Subject: [PATCH 2/7] __init__.py: also allow for non-github.com github domains --- src/pydata_sphinx_theme/__init__.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 3ea7e75b3..a4f40c66b 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -277,18 +277,19 @@ def setup(app: Sphinx) -> Dict[str, str]: app.add_html_theme("pydata_sphinx_theme", str(theme_path)) if hasattr(app.config, "html_context"): - gitlab_url = app.config.html_context.get("gitlab_url", "") + github_url = app.config.html_content.get("github_url", None) + gitlab_url = app.config.html_context.get("gitlab_url", None) - if gitlab_url.startswith("https://"): - gitlab_url = {gitlab_url[8:].rstrip("/"): "gitlab"} - elif gitlab_url.startswith("http://"): - gitlab_url = {gitlab_url[7:].rstrip("/"): "gitlab"} - else: - gitlab_url = {} + url_update = {} + for url, platform in zip([github_url, gitlab_url], ["github", "gitlab"]): + if url: + # remove "http[s]://" and leading/trailing "/"s + url = urlparse(url)._replace(scheme="").geturl().lstrip("/").rstrip("/") + url_update[url] = platform class ShortenLinkTransformCustom(short_link.ShortenLinkTransform): supported_platform = short_link.ShortenLinkTransform.supported_platform - supported_platform.update(gitlab_url) + supported_platform.update(url_update) app.add_post_transform(ShortenLinkTransformCustom) else: From 9f9df680eae6786bcd75713287077bce3fd7f360 Mon Sep 17 00:00:00 2001 From: Matthew Pitkin Date: Wed, 4 Dec 2024 14:55:26 +0000 Subject: [PATCH 3/7] Add ability to shorten bitbucket links --- .../assets/styles/base/_base.scss | 7 ++++++- .../assets/styles/variables/_icons.scss | 1 + src/pydata_sphinx_theme/short_link.py | 18 ++++++++++++++++-- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/src/pydata_sphinx_theme/assets/styles/base/_base.scss b/src/pydata_sphinx_theme/assets/styles/base/_base.scss index 5ebd8bd06..e76776e06 100644 --- a/src/pydata_sphinx_theme/assets/styles/base/_base.scss +++ b/src/pydata_sphinx_theme/assets/styles/base/_base.scss @@ -48,7 +48,8 @@ a { // set up a icon next to the shorten links from github and gitlab &.github, - &.gitlab { + &.gitlab, + &.bitbucket { &::before { color: var(--pst-color-text-muted); font: var(--fa-font-brands); @@ -63,6 +64,10 @@ a { &.gitlab::before { content: var(--pst-icon-gitlab); } + + &.bitbucket::before { + content: var(--pst-icon-bitbucket); + } } %heading-style { diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_icons.scss b/src/pydata_sphinx_theme/assets/styles/variables/_icons.scss index f7618ec4e..9db8fff4e 100644 --- a/src/pydata_sphinx_theme/assets/styles/variables/_icons.scss +++ b/src/pydata_sphinx_theme/assets/styles/variables/_icons.scss @@ -20,6 +20,7 @@ html { --pst-icon-search-minus: "\f010"; // fa-solid fa-magnifying-glass-minus --pst-icon-github: "\f09b"; // fa-brands fa-github --pst-icon-gitlab: "\f296"; // fa-brands fa-gitlab + --pst-icon-bitbucket: "\f171"; // fa-brands fa-bitbucket --pst-icon-share: "\f064"; // fa-solid fa-share --pst-icon-bell: "\f0f3"; // fa-solid fa-bell --pst-icon-pencil: "\f303"; // fa-solid fa-pencil diff --git a/src/pydata_sphinx_theme/short_link.py b/src/pydata_sphinx_theme/short_link.py index 34db161e4..10adffba4 100644 --- a/src/pydata_sphinx_theme/short_link.py +++ b/src/pydata_sphinx_theme/short_link.py @@ -12,8 +12,8 @@ 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 link when they are coming from github, gitlab, or bitbucket and add + an extra class to the tag for further styling. Before: .. code-block:: html @@ -37,6 +37,7 @@ class ShortenLinkTransform(SphinxPostTransform): supported_platform: ClassVar[dict[str, str]] = { "github.com": "github", "gitlab.com": "gitlab", + "bitbucket.org": "bitbucket", } platform = None @@ -96,6 +97,19 @@ def parse_url(self, uri: ParseResult) -> str: if parts[2] in ["issues", "pull", "discussions"]: text += f"#{parts[-1]}" # element number + elif self.platform == "bitbucket": + # split the url content + parts = path.split("/") + + if len(parts) > 0: + text = parts[0] # organisation + if len(parts) > 1: + text += f"/{parts[1]}" # repository + if len(parts) > 2: + if parts[2] in ["issues", "pull-requests"]: + itemnumber = parts[3] + text += f"#{itemnumber}" # element number + elif self.platform == "gitlab": # cp. https://docs.gitlab.com/ee/user/markdown.html#gitlab-specific-references if "/-/" in path and any( From 617b97781a69a443019081661041b3693d4a94db Mon Sep 17 00:00:00 2001 From: Matthew Pitkin Date: Wed, 4 Dec 2024 14:57:31 +0000 Subject: [PATCH 4/7] __init__.py: add custum bitbucket url --- src/pydata_sphinx_theme/__init__.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index a4f40c66b..992718334 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -279,9 +279,12 @@ def setup(app: Sphinx) -> Dict[str, str]: if hasattr(app.config, "html_context"): github_url = app.config.html_content.get("github_url", None) gitlab_url = app.config.html_context.get("gitlab_url", None) + bitbucket_url = app.config.html_content.get("bitbucket_url", None) url_update = {} - for url, platform in zip([github_url, gitlab_url], ["github", "gitlab"]): + for url, platform in zip( + [github_url, gitlab_url, bitbucket_url], ["github", "gitlab", "bitbucket"] + ): if url: # remove "http[s]://" and leading/trailing "/"s url = urlparse(url)._replace(scheme="").geturl().lstrip("/").rstrip("/") From 277730fadbed61adde275e02e2a27fbc0103383f Mon Sep 17 00:00:00 2001 From: Matthew Pitkin Date: Wed, 4 Dec 2024 15:07:19 +0000 Subject: [PATCH 5/7] __init__.py: fix typo html_content -> html_context --- src/pydata_sphinx_theme/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 992718334..e371faf57 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -277,9 +277,9 @@ def setup(app: Sphinx) -> Dict[str, str]: app.add_html_theme("pydata_sphinx_theme", str(theme_path)) if hasattr(app.config, "html_context"): - github_url = app.config.html_content.get("github_url", None) + github_url = app.config.html_context.get("github_url", None) gitlab_url = app.config.html_context.get("gitlab_url", None) - bitbucket_url = app.config.html_content.get("bitbucket_url", None) + bitbucket_url = app.config.html_context.get("bitbucket_url", None) url_update = {} for url, platform in zip( From 86dd4181fcecb7a48014be63befd7d7c8a0a06e8 Mon Sep 17 00:00:00 2001 From: Matthew Pitkin Date: Wed, 4 Dec 2024 16:58:16 +0000 Subject: [PATCH 6/7] short_link.py: treatmemt for bitbucket workspace/overview URLs --- src/pydata_sphinx_theme/short_link.py | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/pydata_sphinx_theme/short_link.py b/src/pydata_sphinx_theme/short_link.py index 10adffba4..bd55955d6 100644 --- a/src/pydata_sphinx_theme/short_link.py +++ b/src/pydata_sphinx_theme/short_link.py @@ -103,12 +103,15 @@ def parse_url(self, uri: ParseResult) -> str: if len(parts) > 0: text = parts[0] # organisation - if len(parts) > 1: - text += f"/{parts[1]}" # repository - if len(parts) > 2: - if parts[2] in ["issues", "pull-requests"]: - itemnumber = parts[3] - text += f"#{itemnumber}" # element number + if len(parts) > 1 and not ( + parts[-2] == "workspace" and parts[-1] == "overview" + ): + if len(parts) > 1: + text += f"/{parts[1]}" # repository + if len(parts) > 2: + if parts[2] in ["issues", "pull-requests"]: + itemnumber = parts[3] + text += f"#{itemnumber}" # element number elif self.platform == "gitlab": # cp. https://docs.gitlab.com/ee/user/markdown.html#gitlab-specific-references From 96a1812f3ca18c260d7a247c32f202b8e2e8e989 Mon Sep 17 00:00:00 2001 From: Matthew Pitkin Date: Wed, 4 Dec 2024 16:58:32 +0000 Subject: [PATCH 7/7] Update documentation --- docs/user_guide/source-buttons.rst | 2 ++ docs/user_guide/theme-elements.md | 22 +++++++++++++++++++++- 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/user_guide/source-buttons.rst b/docs/user_guide/source-buttons.rst index a4db469ad..249ca8454 100644 --- a/docs/user_guide/source-buttons.rst +++ b/docs/user_guide/source-buttons.rst @@ -4,6 +4,8 @@ Source Buttons Source buttons are links to the source of your page's content (either on your site, or on hosting sites like GitHub). +.. _add-edit-button: + Add an edit button ================== diff --git a/docs/user_guide/theme-elements.md b/docs/user_guide/theme-elements.md index 3e54a750d..43936db77 100644 --- a/docs/user_guide/theme-elements.md +++ b/docs/user_guide/theme-elements.md @@ -212,7 +212,7 @@ All will end up as numbers in the rendered HTML, but in the source they look lik ## Link shortening for git repository services -Many projects have links back to their issues / PRs hosted on platforms like **GitHub** or **GitLab**. +Many projects have links back to their issues / PRs hosted on platforms like **GitHub**, **GitLab**, or **Bitbucket**. Instead of displaying these as raw links, this theme does some lightweight formatting for these platforms specifically. In **reStructuredText**, URLs are automatically converted to links, so this works automatically. @@ -252,5 +252,25 @@ There are a variety of link targets supported, here's a table for reference: - `https://gitlab.com/gitlab-org`: https://gitlab.com/gitlab-org - `https://gitlab.com/gitlab-org/gitlab`: https://gitlab.com/gitlab-org/gitlab - `https://gitlab.com/gitlab-org/gitlab/-/issues/375583`: https://gitlab.com/gitlab-org/gitlab/-/issues/375583 +- `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174667`: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174667 + +**Bitbucket** + +- `https://bitbucket.org`: https://bitbucket.org +- `https://bitbucket.org/atlassian/workspace/overview`: https://bitbucket.org/atlassian/workspace/overview +- `https://bitbucket.org/atlassian/aui`: https://bitbucket.org/atlassian/aui +- `https://bitbucket.org/atlassian/aui/pull-requests/4758`: https://bitbucket.org/atlassian/aui/pull-requests/4758 Links provided with a text body won't be changed. + +If you have links to GitHub, GitLab, or Bitbucket repository URLs that are on non-standard domains +(i.e., not on `github.com`, `gitlab.com`, or `bitbucket.org`, respectively), then these will be +shortened if the base URL is given in the `html_context` section of your `conf.py` file (see +{ref}`Add an edit button `), e.g., + +```python +html_context = { + "gitlab_url": "https://gitlab.mydomain.com", # your self-hosted GitLab + ... +} +```