Make icon links and link shortening optional (#2109)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: gabalafou <[email protected]>
Co-authored-by: Daniel McCloy <[email protected]>

Author: 4 people

src/pydata_sphinx_theme/__init__.py

@@ -44,6 +44,8 @@ def update_config(app):
         raise ExtensionError(
             "`icon_links` must be a list of dictionaries, you provided "
             f"type {type(theme_options.get('icon_links'))}."
+            "If you wish to disable this feature, either do not provide "
+            "a value (leave undefined), or set to an empty list."
         )
 
     # Set the anchor link default to be # if the user hasn't provided their own
@@ -282,7 +284,9 @@ def setup(app: Sphinx) -> Dict[str, str]:
 
     app.add_html_theme("pydata_sphinx_theme", str(theme_path))
 
-    app.add_post_transform(short_link.ShortenLinkTransform)
+    theme_options = utils.get_theme_options_dict(app)
+    if theme_options.get("shorten_urls"):
+        app.add_post_transform(short_link.ShortenLinkTransform)
 
     app.connect("builder-inited", translator.setup_translators)
     app.connect("builder-inited", update_config)

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -37,6 +37,7 @@ logo_link =
 surface_warnings = True
 back_to_top_button = True
 search_as_you_type = False
+shorten_urls = True
 
 # Template placement in theme layouts
 navbar_start = navbar-logo

tests/test_build.py

@@ -844,7 +844,10 @@ def test_theme_switcher(sphinx_build_factory, file_regression) -> None:
 
 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()
+    confoverrides = {
+        "html_theme_options": {"shorten_urls": True},
+    }
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
 
     github = sphinx_build.html_tree("page1.html").select(".github-container")[0]
     file_regression.check(github.prettify(), basename="github_links", extension=".html")
@@ -853,6 +856,24 @@ def test_shorten_link(sphinx_build_factory, file_regression) -> None:
     file_regression.check(gitlab.prettify(), basename="gitlab_links", extension=".html")
 
 
+def test_dont_shorten_link(sphinx_build_factory, file_regression) -> None:
+    """Regression test for setting shorten_urls to false ."""
+    confoverrides = {
+        "html_theme_options": {"shorten_urls": False},
+    }
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+
+    github = sphinx_build.html_tree("page1.html").select(".github-container")[0]
+    file_regression.check(
+        github.prettify(), basename="github_links_not_shortened", extension=".html"
+    )
+
+    gitlab = sphinx_build.html_tree("page1.html").select(".gitlab-container")[0]
+    file_regression.check(
+        gitlab.prettify(), basename="gitlab_links_not_shortened", extension=".html"
+    )
+
+
 def test_math_header_item(sphinx_build_factory, file_regression) -> None:
     """Regression test for math items in a header title."""
     sphinx_build = sphinx_build_factory("base").build()

tests/test_build/github_links_not_shortened.html

@@ -0,0 +1,19 @@
+<div class="github-container docutils container">
+ <p>
+  <a class="reference external" href="https://github.com">
+   https://github.com
+  </a>
+  <a class="reference external" href="https://github.com/pydata">
+   https://github.com/pydata
+  </a>
+  <a class="reference external" href="https://github.com/pydata/pydata-sphinx-theme">
+   https://github.com/pydata/pydata-sphinx-theme
+  </a>
+  <a class="reference external" href="https://github.com/pydata/pydata-sphinx-theme/pull/1012">
+   https://github.com/pydata/pydata-sphinx-theme/pull/1012
+  </a>
+  <a class="reference external" href="https://github.com/orgs/pydata/projects/2">
+   https://github.com/orgs/pydata/projects/2
+  </a>
+ </p>
+</div>

tests/test_build/gitlab_links_not_shortened.html

@@ -0,0 +1,40 @@
+<div class="gitlab-container docutils container">
+ <p>
+  <a class="reference external" href="https://gitlab.com">
+   https://gitlab.com
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org">
+   https://gitlab.com/gitlab-org
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab">
+   https://gitlab.com/gitlab-org/gitlab
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab/-/issues/375583">
+   https://gitlab.com/gitlab-org/gitlab/-/issues/375583
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab/issues/375583">
+   https://gitlab.com/gitlab-org/gitlab/issues/375583
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab/-/issues/">
+   https://gitlab.com/gitlab-org/gitlab/-/issues/
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab/issues/">
+   https://gitlab.com/gitlab-org/gitlab/issues/
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab/-/issues">
+   https://gitlab.com/gitlab-org/gitlab/-/issues
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab/issues">
+   https://gitlab.com/gitlab-org/gitlab/issues
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84669">
+   https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84669
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-org/gitlab/-/pipelines/511894707">
+   https://gitlab.com/gitlab-org/gitlab/-/pipelines/511894707
+  </a>
+  <a class="reference external" href="https://gitlab.com/gitlab-com/gl-infra/production/-/issues/6788">
+   https://gitlab.com/gitlab-com/gl-infra/production/-/issues/6788
+  </a>
+ </p>
+</div>