NEH: Icon links, latest PST, more source providers, and bug fixes (#691)

Author: choldgraf

docs/_static/ebp-logo.png

@@ -0,0 +1,5 @@
+# Icon links and badges
+
+You can add a collection of icon links and badges to your primary sidebar.
+For example, to include links to your GitHub repository or a [shields.io badge](https://shields.io).
+See the {external:ref}`PyData Icon Links documentation <icon-links>` for how to configure this.

docs/components/icon-links.md

@@ -4,6 +4,7 @@ Components are specific UI elements that you can control with configuration.
 
 ```{toctree}
 logo
+icon-links
 download
 source-files
 custom-css

docs/components/index.md

@@ -3,78 +3,123 @@
 
 There are a collection of buttons that you can use to link back to your source
 repository. This lets users browse the repository, or take actions like suggest
-an edit or open an issue. In each case, they require the following configuration
-to exist:
+an edit or open an issue.
+
+(source-buttons:repository)=
+## Set your source repository
+
+You need to define a **source repository** for this functionality to work.
+This is the online space where your code / documentation is hosted.
+To
+In each case, they require the following configuration to exist:
 
 ```python
 html_theme_options = {
     ...
-    "repository_url": "https://github.com/{your-docs-url}",
+    "repository_url": "https://{your-provider}/{org}/{repo}",
     ...
 }
 ```
 
-(source-files:repository)=
-## Add a link to your repository
+Three providers are supported:
 
-To add a link to your repository, add the following configuration:
+- **GitHub**: For example, `https://github.com/executablebooks/sphinx-book-theme`.
+  This includes custom URLs for self-hosted GitHub.
+- **GitLab**: For example, `https://gitlab.com/gitlab-org/gitlab`.
+  This includes custom URLs for self-hosted GitLab.
+- **BitBucket**: For example, `https://opensource.ncsa.illinois.edu/bitbucket/scm/u3d/3dutilities`.
+
+In each case, we **assume the final two URL items are the `org/repo` pair**.
+
+### Manually specify the provider
+
+If your provider URL is more complex (e.g., if you're self-hosting your provider), you can manually specify the provider with the following configuration:
 
 ```python
 html_theme_options = {
     ...
-    "repository_url": "https://github.com/{your-docs-url}",
-    "use_repository_button": True,
+    "repository_provider": "gitlab"  # or "github", "bitbucket",
+    "repository_url": "selfhostedgh.mycompany.org/user/repo",
     ...
 }
 ```
 
-## Add a button to open issues
+Once this is provided, you may add source buttons by following the following sections.
 
-To add a button to open an issue about the current page, use the following
-configuration:
+(source-buttons:source)=
+## Add a button to the page source
+
+Show the raw source of the page on the provider you've proivded.
+To add a button to the page source, first [configure your source repository](source-buttons:repository) and then add:
 
 ```python
 html_theme_options = {
     ...
-    "repository_url": "https://github.com/{your-docs-url}",
-    "use_issues_button": True,
+    "use_source_button": True,
+    ...
+}
+```
+
+Then configure the **repository branch** to use for your source.
+By default it is `main`, but if you'd like to change this, use the following configuration:
+
+```python
+html_theme_options = {
+    ...
+    "repository_branch": "{your-branch}",
+    ...
+}
+```
+
+Finally, **configure the relative path to your documentation**.
+By default, this is the root of the repository, but if your documentation is hosted in a sub-folder, use the following configuration:
+
+```python
+html_theme_options = {
+    ...
+    "path_to_docs": "{path-relative-to-site-root}",
     ...
 }
 ```
 
 ## Add a button to suggest edits
 
-You can add a button to each page that will allow users to edit the page text
-directly and submit a pull request to update the documentation. To include this
-button, use the following configuration:
+Allow users to edit the page text directly on the provider and submit a pull request to update the documentation.
+To add a button to edit the page, first [configure your source repository](source-buttons:repository) and then add:
 
 ```python
 html_theme_options = {
     ...
-    "repository_url": "https://github.com/{your-docs-url}",
     "use_edit_page_button": True,
     ...
 }
 ```
 
-By default, the edit button will point to the `master` branch, but if you'd like
-to change this, use the following configuration:
+Then follow the [branch and relative path instructions in the source file section](source-buttons:source).
+
+
+(source-files:repository)=
+## Add a link to your repository
+
+To add a link to your repository, add the following configuration:
 
 ```python
 html_theme_options = {
     ...
-    "repository_branch": "{your-branch}",
+    "use_repository_button": True,
     ...
 }
 ```
 
-By default, the edit button will point to the root of the repository. If your
-documentation is hosted in a sub-folder, use the following configuration:
+## Add a button to open issues
+
+To add a button to open an issue about the current page, use the following
+configuration:
 
 ```python
 html_theme_options = {
     ...
-    "path_to_docs": "{path-relative-to-site-root}",
+    "use_issues_button": True,
     ...
 }
 ```

docs/components/source-files.md

@@ -108,7 +108,7 @@
 html_theme_options = {
     "path_to_docs": "docs",
     "repository_url": "https://github.com/executablebooks/sphinx-book-theme",
-    # "repository_branch": "gh-pages",  # For testing
+    "repository_branch": "master",
     "launch_buttons": {
         "binderhub_url": "https://mybinder.org",
         "colab_url": "https://colab.research.google.com/",
@@ -118,8 +118,9 @@
         # "jupyterhub_url": "https://datahub.berkeley.edu",  # For testing
     },
     "use_edit_page_button": True,
+    "use_source_button": True,
     "use_issues_button": True,
-    "use_repository_button": True,
+    # "use_repository_button": True,
     "use_download_button": True,
     "use_sidenotes": True,
     "show_toc_level": 2,
@@ -131,6 +132,25 @@
         "image_dark": "_static/logo-wide-dark.svg",
         # "text": html_title,  # Uncomment to try text with logo
     },
+    "icon_links": [
+        {
+            "name": "Executable Books",
+            "url": "https://executablebooks.org/",
+            "icon": "_static/ebp-logo.png",
+            "type": "local",
+        },
+        {
+            "name": "GitHub",
+            "url": "https://github.com/executablebooks/sphinx-book-theme",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/sphinx-book-theme/",
+            "icon": "https://img.shields.io/pypi/dw/sphinx-book-theme",
+            "type": "url",
+        },
+    ],
     # For testing
     # "use_fullscreen_button": False,
     # "home_page_in_toc": True,

docs/conf.py

@@ -62,7 +62,7 @@ To add Google Colab links to your page, add the following configuration:
 html_theme_options = {
     ...
     "launch_buttons": {
-        "colab_url": "https://{your-colab-url}"
+        "colab_url": "https://colab.research.google.com"
     },
     ...
 }

docs/content/launch.md

@@ -23,7 +23,7 @@ readme = "README.md"
 requires-python = ">=3.7"
 dependencies = [
   "sphinx>=4,<7",
-  "pydata-sphinx-theme>=0.13.0rc4",
+  "pydata-sphinx-theme>=0.13.0rc5",
 ]
 
 license = { file = "LICENSE" }

pyproject.toml

@@ -9,10 +9,17 @@
 from sphinx.application import Sphinx
 from sphinx.locale import get_translation
 from sphinx.util import logging
+from pydata_sphinx_theme import _get_theme_options
 
 from .nodes import SideNoteNode
-from .header_buttons import prep_header_buttons, add_header_buttons, update_sourcename
+from .header_buttons import (
+    prep_header_buttons,
+    add_header_buttons,
+    update_sourcename,
+    update_context_with_repository_info,
+)
 from .header_buttons.launch import add_launch_buttons
+from .header_buttons.source import add_source_buttons
 from ._transforms import HandleFootnoteTransform
 
 __version__ = "1.0.0rc2"
@@ -60,7 +67,7 @@ def add_metadata_to_page(app, pagename, templatename, context, doctree):
     context["translate"] = translation
 
     # If search text hasn't been manually specified, use a shorter one here
-    theme_options = app.builder.theme_options or {}
+    theme_options = _get_theme_options(app)
     if "search_bar_text" not in theme_options:
         context["theme_search_bar_text"] = translation("Search") + "..."
 
@@ -89,7 +96,7 @@ def hash_assets_for_files(assets: list, theme_static: Path, context):
             asset_sphinx_link = f"_static/{asset}"
             asset_source_path = theme_static / asset
             if not asset_source_path.exists():
-                SPHINX_LOGGER.warn(
+                SPHINX_LOGGER.warning(
                     f"Asset {asset_source_path} does not exist, not linking."
                 )
             # Find this asset in context, and update it to include the digest
@@ -115,7 +122,7 @@ def hash_html_assets(app, pagename, templatename, context, doctree):
 
 def update_mode_thebe_config(app):
     """Update thebe configuration with SBT-specific values"""
-    theme_options = app.builder.theme_options
+    theme_options = _get_theme_options(app)
     if theme_options.get("launch_buttons", {}).get("thebe") is True:
         # In case somebody specifies they want thebe in a launch button
         # but has not activated the sphinx_thebe extension.
@@ -154,7 +161,7 @@ def check_deprecation_keys(app):
 
     deprecated_config_list = ["single_page"]
     for key in deprecated_config_list:
-        if key in app.builder.theme_options:
+        if key in _get_theme_options(app):
             SPHINX_LOGGER.warning(
                 f"'{key}' was deprecated from version 0.3.4 onwards. See the CHANGELOG for more information: https://github.com/executablebooks/sphinx-book-theme/blob/master/CHANGELOG.md"  # noqa: E501
                 f"[{DEFAULT_LOG_TYPE}]",
@@ -181,14 +188,14 @@ def run(self):
         return nodes
 
 
-def update_general_config(app, config):
+def update_general_config(app):
     theme_dir = get_html_theme_path()
     # Update templates for sidebar. Needed for jupyter-book builds as jb
     # uses an instance of Sphinx class from sphinx.application to build the app.
     # The __init__ function of which calls self.config.init_values() just
     # before emitting `config-inited` event. The init_values function overwrites
     # templates_path variable.
-    config.templates_path.append(os.path.join(theme_dir, "components"))
+    app.config.templates_path.append(os.path.join(theme_dir, "components"))
 
 
 def update_templates(app, pagename, templatename, context, doctree):
@@ -227,7 +234,8 @@ def setup(app: Sphinx):
     app.connect("builder-inited", update_mode_thebe_config)
     app.connect("builder-inited", check_deprecation_keys)
     app.connect("builder-inited", update_sourcename)
-    app.connect("config-inited", update_general_config)
+    app.connect("builder-inited", update_context_with_repository_info)
+    app.connect("builder-inited", update_general_config)
     app.connect("html-page-context", add_metadata_to_page)
     app.connect("html-page-context", hash_html_assets)
     app.connect("html-page-context", update_templates)
@@ -237,8 +245,9 @@ def setup(app: Sphinx):
 
     # Header buttons
     app.connect("html-page-context", prep_header_buttons)
-    app.connect("html-page-context", add_launch_buttons)
-    # Bump priority by 1 so that it runs after the pydata theme sets up the edit URL.
+    # Bump priority so that it runs after the pydata theme sets up the edit URL func.
+    app.connect("html-page-context", add_launch_buttons, priority=501)
+    app.connect("html-page-context", add_source_buttons, priority=501)
     app.connect("html-page-context", add_header_buttons, priority=501)
 
     # Directives

src/sphinx_book_theme/__init__.py

@@ -2,6 +2,7 @@
 from typing import Any
 from docutils import nodes as docutil_nodes
 from sphinx import addnodes as sphinx_nodes
+from pydata_sphinx_theme import _get_theme_options
 from .nodes import SideNoteNode
 
 
@@ -12,7 +13,7 @@ class HandleFootnoteTransform(SphinxPostTransform):
     formats = ("html",)
 
     def run(self, **kwargs: Any) -> None:
-        theme_options = self.app.builder.theme_options
+        theme_options = _get_theme_options(self.app)
         if theme_options.get("use_sidenotes", False) is False:
             return None
         # Cycle through footnote references, and move their content next to the

src/sphinx_book_theme/_transforms.py

@@ -0,0 +1,21 @@
+/**
+ * Icon links design for the primary sidebar, where it defaults in this theme.
+ */
+.bd-sidebar-primary {
+  .navbar-icon-links {
+    column-gap: 0.5rem;
+
+    .nav-link {
+      // There are few kinds of elements that can be icon links and each is different
+      i,
+      span {
+        font-size: 1.2rem;
+      }
+
+      // Images usually fill more vertical space so we make them a bit smaller
+      img {
+        font-size: 0.8rem;
+      }
+    }
+  }
+}