ENH - edit button support for codeberg, forgejo, gitea

Signed-off-by: Martin Matous <m@matous.dev>

Author: mmatous

docs/user_guide/source-buttons.rst

@@ -19,7 +19,7 @@ your ``conf.py`` file in 'html_theme_options':
    }
 
 A number of providers are available for building *Edit this Page* links, including
-GitHub, GitLab, and Bitbucket. For each, the default public instance URL can be
+GitHub, GitLab, Bitbucket, Forgejo and Gitea. For each, the default public instance URL (should it exist) can be
 replaced with a self-hosted instance.
 
 
@@ -65,6 +65,33 @@ Bitbucket
    }
 
 
+Forgejo
+---------
+
+.. code:: python
+
+   html_context = {
+       # "forgejo_url": "https://codeberg.org", # or your self-hosted Forgejo
+       "forgejo_user": "<your-forgejo-org>",
+       "forgejo_repo": "<your-forgejo-repo>",
+       "forgejo_version": "<your-branch>",
+       "doc_path": "<path-from-root-to-your-docs>",
+   }
+
+
+Gitea
+---------
+
+.. code:: python
+
+   html_context = {
+       # "gitea_url": "https://gitea.com", # or your self-hosted Gitea
+       "gitea_user": "<your-gitea-org>",
+       "gitea_repo": "<your-gitea-repo>",
+       "gitea_version": "<your-branch>",
+       "doc_path": "<path-from-root-to-your-docs>",
+   }
+
 Custom Edit URL
 ---------------
 
@@ -80,7 +107,7 @@ any other context values.
        "some_other_arg": "?some-other-arg"
    }
 
-With the predefined providers, the link text reads "Edit on GitHub/GitLab/Bitbucket".
+With the predefined providers, the link text reads "Edit on GitHub/GitLab/Bitbucket/Codeberg/Forgejo/Gitea".
 By default, a simple "Edit" is used if you use a custom URL. However, you can set
 a provider name like this:
 

src/pydata_sphinx_theme/edit_this_page.py

@@ -1,10 +1,14 @@
 """Create an "edit this page" url compatible with bitbucket, gitlab and github."""
 
+import urllib
+
 import jinja2
 
 from sphinx.application import Sphinx
 from sphinx.errors import ExtensionError
 
+from .utils import get_theme_options_dict
+
 
 def setup_edit_url(
     app: Sphinx, pagename: str, templatename: str, context, doctree
@@ -20,11 +24,24 @@ def get_edit_provider_and_url() -> None:
         if doc_path and not doc_path.endswith("/"):
             doc_path = f"{doc_path}/"
 
-        default_provider_urls = {
+        provider_urls = {
             "bitbucket_url": "https://bitbucket.org",
+            "forgejo_url": "https://codeberg.org",
+            "gitea_url": "https://gitea.com",
             "github_url": "https://github.com",
             "gitlab_url": "https://gitlab.com",
         }
+        provider_labels = {
+            "bitbucket": "Bitbucket",
+            "forgejo": "Forgejo",
+            "gitea": "Gitea",
+            "github": "GitHub",
+            "gitlab": "GitLab",
+        }
+        theme_options = get_theme_options_dict(app)
+        provider_urls, provider_labels = adjust_forge_params(
+            provider_urls, provider_labels, theme_options
+        )
 
         edit_attrs = {}
 
@@ -44,25 +61,35 @@ def get_edit_provider_and_url() -> None:
         edit_attrs.update(
             {
                 ("bitbucket_user", "bitbucket_repo", "bitbucket_version"): (
-                    "Bitbucket",
+                    provider_labels["bitbucket"],
                     "{{ bitbucket_url }}/{{ bitbucket_user }}/{{ bitbucket_repo }}"
                     "/src/{{ bitbucket_version }}"
                     "/{{ doc_path }}{{ file_name }}?mode=edit",
                 ),
+                ("forgejo_user", "forgejo_repo", "forgejo_version"): (
+                    provider_labels["forgejo"],
+                    "{{ forgejo_url }}/{{ forgejo_user }}/{{ forgejo_repo }}"
+                    "/_edit/{{ forgejo_version }}/{{ doc_path }}{{ file_name }}",
+                ),
+                ("gitea_user", "gitea_repo", "gitea_version"): (
+                    provider_labels["gitea"],
+                    "{{ gitea_url }}/{{ gitea_user }}/{{ gitea_repo }}"
+                    "/_edit/{{ gitea_version }}/{{ doc_path }}{{ file_name }}",
+                ),
                 ("github_user", "github_repo", "github_version"): (
-                    "GitHub",
+                    provider_labels["github"],
                     "{{ github_url }}/{{ github_user }}/{{ github_repo }}"
                     "/edit/{{ github_version }}/{{ doc_path }}{{ file_name }}",
                 ),
                 ("gitlab_user", "gitlab_repo", "gitlab_version"): (
-                    "GitLab",
+                    provider_labels["gitlab"],
                     "{{ gitlab_url }}/{{ gitlab_user }}/{{ gitlab_repo }}"
                     "/-/edit/{{ gitlab_version }}/{{ doc_path }}{{ file_name }}",
                 ),
             }
         )
 
-        doc_context = dict(default_provider_urls)
+        doc_context = dict(provider_urls)
         doc_context.update(context)
         doc_context.update(doc_path=doc_path, file_name=file_name)
 
@@ -80,3 +107,27 @@ def get_edit_provider_and_url() -> None:
 
     # Ensure that the max TOC level is an integer
     context["theme_show_toc_level"] = int(context.get("theme_show_toc_level", 1))
+
+
+def adjust_forge_params(
+    forge_urls: dict[str, str],
+    forge_labels: dict[str, str],
+    theme_options: dict[str, str],
+) -> (dict[str, str], dict[str, str]):
+    """Adjust labels and URLs for some of the more decentralized forges."""
+    # use *_urls given in html_theme_options as authority (netloc)
+    # instead of default if available
+    for url_key in forge_urls:
+        forge_url = theme_options.get(url_key)
+        if forge_url:
+            forge_url = urllib.parse.urlsplit(forge_url, allow_fragments=False)
+            forge_url = f"{forge_url.scheme}://{forge_url.netloc}"
+            forge_urls[url_key] = forge_url
+
+    # use rebranded forge label instead of generic SW name where known
+    if "forgejo_url" in theme_options:
+        url = theme_options["forgejo_url"]
+        if url.startswith("https://codeberg.org"):
+            forge_labels["forgejo"] = "Codeberg"
+
+    return forge_urls, forge_labels

tests/test_build.py

@@ -585,6 +585,44 @@ def test_footer(sphinx_build_factory) -> None:
             "https://bitbucket.org/foo/bar/src/HEAD/docs/index.rst?mode=edit",
         ),
     ],
+    [
+        {
+            "forgejo_user": "foo",
+            "forgejo_repo": "bar",
+            "forgejo_version": "HEAD",
+            "doc_path": "docs",
+            "forgejo_url": "https://my-forgejo.com",
+        },
+        (
+            "Edit on Forgejo",
+            "https://my-forgejo.com/foo/bar/_edit/HEAD/docs/index.rst",
+        ),
+    ],
+    [
+        {
+            "forgejo_user": "foo",
+            "forgejo_repo": "bar",
+            "forgejo_version": "HEAD",
+            "doc_path": "docs",
+            "forgejo_url": "https://codeberg.org",
+        },
+        (
+            "Edit on Codeberg",
+            "https://codeberg.org/foo/bar/_edit/HEAD/docs/index.rst",
+        ),
+    ],
+    [
+        {
+            "gitea_user": "foo",
+            "gitea_repo": "bar",
+            "gitea_version": "HEAD",
+            "doc_path": "docs",
+        },
+        (
+            "Edit on Gitea",
+            "https://gitea.com/foo/bar/_edit/HEAD/docs/index.rst",
+        ),
+    ],
 ]
 
 
@@ -608,16 +646,22 @@ def test_footer(sphinx_build_factory) -> None:
         dict(
             # copy all the values
             **html_context,
-            # add a provider url
-            **{f"{provider}_url": f"https://{provider}.example.com"},
+            # add a provider url if not specified in html_context
+            **(
+                {f"{provider}_url": f"https://{provider}.example.com"}
+                if f"{provider}_url" not in html_context
+                else {}
+            ),
         ),
         (
             text,
-            f"""https://{provider}.example.com/foo/{url.split("/foo/")[1]}""",
+            f"""https://{provider}.example.com/foo/{url.split("/foo/")[1]}"""
+            if f"{provider}_url" not in html_context
+            else f"{html_context[f'{provider}_url']}/foo/{url.split('/foo/')[1]}",
         ),
     ]
     for html_context, (text, url) in good_edits
-    for provider in ["github", "gitlab", "bitbucket"]
+    for provider in ["github", "gitlab", "bitbucket", "forgejo", "gitea"]
     if provider in text.lower()
 ]
 
@@ -687,6 +731,10 @@ def test_edit_page_url(sphinx_build_factory, html_context, edit_text_and_url) ->
         "html_theme_options.use_edit_page_button": True,
         "html_context": html_context,
     }
+    if html_context.get("forgejo_url"):
+        confoverrides.update(
+            {"html_theme_options.forgejo_url": html_context["forgejo_url"]}
+        )
     sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides)
 
     if edit_text_and_url is None:

tests/test_edit.py

@@ -0,0 +1,70 @@
+"""Edit button unit tests."""
+
+import pytest
+
+from pydata_sphinx_theme.edit_this_page import adjust_forge_params
+
+
+@pytest.fixture
+def default_forge_urls():
+    """Setup default edit URLs."""
+    return {
+        "forgejo_url": "https://codeberg.org",
+        "gitea_url": "https://gitea.com",
+        "gitlab_url": "https://gitlab.com",
+    }
+
+
+@pytest.mark.parametrize(
+    "html_theme_options,modified_urls",
+    [
+        (
+            {"forgejo_url": "https://my-forgejo.com/f-proj/f-repo"},
+            {"forgejo_url": "https://my-forgejo.com"},
+        ),
+        (
+            {"gitea_url": "https://my-gitea.com/g-proj/g-repo"},
+            {"gitea_url": "https://my-gitea.com"},
+        ),
+        (
+            {
+                "gitlab_url": "https://my-gitlab.org/gl-proj/gl-repo",
+                "forgejo_url": "https://my-forgejo.com/f-proj/f-repo",
+            },
+            {
+                "forgejo_url": "https://my-forgejo.com",
+                "gitlab_url": "https://my-gitlab.org",
+            },
+        ),
+    ],
+)
+def test_adjust_forge_params_replace_urls(
+    default_forge_urls, html_theme_options, modified_urls
+):
+    """Unit test for adjust_forge_params() url replacing."""
+    forge_urls, forge_labels = adjust_forge_params(
+        default_forge_urls, {}, html_theme_options
+    )
+    expected_urls = default_forge_urls | modified_urls
+
+    assert forge_urls == expected_urls
+    assert forge_labels == {}
+
+
+@pytest.mark.parametrize(
+    "html_theme_options,expected_labels",
+    [
+        ({"forgejo_url": "https://noreplace.com"}, {}),
+        ({"forgejo_url": "https://codeberg.org"}, {"forgejo": "Codeberg"}),
+    ],
+)
+def test_adjust_forge_params_relabel(
+    default_forge_urls, html_theme_options, expected_labels
+):
+    """Unit test for adjust_forge_params() relabeling."""
+    forge_urls, forge_labels = adjust_forge_params(
+        default_forge_urls, {}, html_theme_options
+    )
+
+    assert forge_urls == default_forge_urls
+    assert forge_labels == expected_labels