From bd0285119cc8c5a70cac74ff1e192253b7e8225e Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 23 Feb 2023 18:41:15 +0100 Subject: [PATCH 1/8] Icon links documentation --- docs/_static/ebp-logo.png | Bin 0 -> 1507 bytes docs/components/icon-links.md | 5 +++++ docs/components/index.md | 1 + docs/conf.py | 19 ++++++++++++++++ pyproject.toml | 2 +- src/sphinx_book_theme/__init__.py | 7 +++--- src/sphinx_book_theme/_transforms.py | 3 ++- .../assets/styles/components/_icon-links.scss | 21 ++++++++++++++++++ .../assets/styles/index.scss | 1 + .../theme/sphinx_book_theme/theme.conf | 2 +- 10 files changed, 55 insertions(+), 6 deletions(-) create mode 100644 docs/_static/ebp-logo.png create mode 100644 docs/components/icon-links.md create mode 100644 src/sphinx_book_theme/assets/styles/components/_icon-links.scss diff --git a/docs/_static/ebp-logo.png b/docs/_static/ebp-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..191a9ee82d9a19e1759648e9fb301f9a18f29658 GIT binary patch literal 1507 zcmV<91swW`P)A5u8jXC=wX9m6pGP=7SU0qcA_`&gp0&WD*aEB#E2wD^LHkQd-T zR@$jHNRuRl5aBV^jsSur6QLUik$enjr`qFczV8&FvmjWj@V*;NjTaQ2S->s(%q5y2 zLeB1r`T2QTTU(=YGBPs4i(q$mm!_ts$PMv$oMN#UwY0SG(%IQby}iBU1tx+Kr7Gm` z@Q|0iy*=96+TsJXyu8eXkOkHy;`C!jM+a9K%KHWC?&;~Fwzf7Z1y~e>fc3h?(H&$~ zS669aVWDuYnza*SV`JL)O-@eo5f;qM%vfFrOW5Atrercn8yg#@-`unty z4e)t8U_E_(eUwNfXmN3|@I5SIaBxuDf+G|Fjg5`uC+M&m7~KT)Ktw=n5s}=l_=311 z16R={5O)|I9p%MOFlBlr5KDO935^Jwo13O{OzpaaLImUpvIvMhZZgQK%oqhCS3v#( zApioe+cey>2$+IWsZ`PH(5Q)t3Gxb(Cp$8k3>QKG7eHd>lv`NgSp+CA)OW&dgH&{r zEF@0D!^58bUT6X%+yW^!TtR1WWIS6!cXu~0#V9p7vRgX9<2Oy_C>Wk;w)Xl-pZ zo$u`IXx$eo5!Co`aB!e?Utk#{cBTXfWPU8E)sffT#|T6OOl9)cTvu0@FCwUW2-wlm zArN=)y0zv82#swu8Qqm+AeNx(n_fX)FgG`6$`swKB#VlGieYA$cV+OM?B`CX_o|4@ z4|QTuB%_Y5dY@I>!1(w$=@R%8C@?!aTkuyePoSJYtbqW!u28j4psYaWku|#6Y8N<) zfCW;iOJOVIO;I%1%cC;^EDGy}Ql4OGKYaEFWCX1dsN=h%vnd;N-+Y9{yMiPm+d zn1D{7K1k5X`VwWIrl@{koa*|j_rG~Ezu)9SM6P^6b=Pjtr7K^ayT)RQ%+b-^pP3jh z`Ps?Z9g1H6nv90aRBfR1r;qOQZtGa8< zJ=pR4#_6N~=?ydclf3E6G<@?5Z@U$U36>&20M(piAc&DKPVnpUE@tPCDk3;zB>4=L zdFgn4_F0N@&z}_Hm{l9%)BoDuZz}?T3&0i1g|H;m-2@oPR8ZXhTs0zl)?$Z{eJ;fDaIzv1R@%niGWUaKVn zz|4TgmeVROu>=Mqb@1y~R4!otNbXQ{a~o|D1R?=>^I(Ot`)mqgK`UFr)QOS8l;#C= z*oa-`)`WVH2S8ZY^|%$m3+N;w_{sX;MS~tX7QKFhcL*H|B2x`S1R1CJVihohAn^SJ zz98$hUXWEn072mU3H5{LcY$I4mCQl|7lCJxN{8h|TP3K-ZZnVKQjm;%RD3@7lZ)4X z45JC|kfhp$_Z=dXZ` for how to configure this. diff --git a/docs/components/index.md b/docs/components/index.md index b9bdee3f9..92369df83 100644 --- a/docs/components/index.md +++ b/docs/components/index.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 diff --git a/docs/conf.py b/docs/conf.py index 19a5b75a1..7ce96e3a2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -131,6 +131,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/dd/sphinx-book-theme", + "type": "url", + }, + ], # For testing # "use_fullscreen_button": False, # "home_page_in_toc": True, diff --git a/pyproject.toml b/pyproject.toml index 3718da21c..ca31516ea 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" } diff --git a/src/sphinx_book_theme/__init__.py b/src/sphinx_book_theme/__init__.py index 076d9f261..d99ff7b2b 100644 --- a/src/sphinx_book_theme/__init__.py +++ b/src/sphinx_book_theme/__init__.py @@ -9,6 +9,7 @@ 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 @@ -60,7 +61,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") + "..." @@ -115,7 +116,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 +155,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}]", diff --git a/src/sphinx_book_theme/_transforms.py b/src/sphinx_book_theme/_transforms.py index a990d9e55..77b4d8b84 100644 --- a/src/sphinx_book_theme/_transforms.py +++ b/src/sphinx_book_theme/_transforms.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 diff --git a/src/sphinx_book_theme/assets/styles/components/_icon-links.scss b/src/sphinx_book_theme/assets/styles/components/_icon-links.scss new file mode 100644 index 000000000..7565c4c42 --- /dev/null +++ b/src/sphinx_book_theme/assets/styles/components/_icon-links.scss @@ -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: 1rem; + } + + // Images usually fill more vertical space so this + img { + font-size: 0.7rem; + } + } + } +} diff --git a/src/sphinx_book_theme/assets/styles/index.scss b/src/sphinx_book_theme/assets/styles/index.scss index 1c42f7ed0..099dadcd2 100644 --- a/src/sphinx_book_theme/assets/styles/index.scss +++ b/src/sphinx_book_theme/assets/styles/index.scss @@ -27,6 +27,7 @@ @import "sections/footer-article"; // Re-usable components across the theme +@import "components/icon-links"; @import "components/logo"; @import "components/search"; diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf b/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf index 0d03c4ad5..e5428112a 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf @@ -1,7 +1,7 @@ [theme] inherit = pydata_sphinx_theme pygments_style = tango -sidebars = navbar-logo.html, sbt-sidebar-nav.html +sidebars = navbar-logo.html, icon-links.html, sbt-sidebar-nav.html stylesheet = styles/sphinx-book-theme.css [options] From a493d3ccfad400288cadf5dd2fbbb5cf21ec8d95 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 23 Feb 2023 18:50:37 +0100 Subject: [PATCH 2/8] size tweaks --- .../assets/styles/components/_icon-links.scss | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/sphinx_book_theme/assets/styles/components/_icon-links.scss b/src/sphinx_book_theme/assets/styles/components/_icon-links.scss index 7565c4c42..bb6245b36 100644 --- a/src/sphinx_book_theme/assets/styles/components/_icon-links.scss +++ b/src/sphinx_book_theme/assets/styles/components/_icon-links.scss @@ -9,12 +9,12 @@ // There are few kinds of elements that can be icon links and each is different i, span { - font-size: 1rem; + font-size: 1.2rem; } - // Images usually fill more vertical space so this + // Images usually fill more vertical space so we make them a bit smaller img { - font-size: 0.7rem; + font-size: 0.8rem; } } } From 1d2a5a5b05d6c01a3a54878c570c3e7ab4442c69 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sat, 25 Feb 2023 15:09:19 +0100 Subject: [PATCH 3/8] Add support for more source repositories --- docs/components/source-files.md | 88 +++++++--- docs/conf.py | 5 +- .../header_buttons/__init__.py | 156 +++++++++++++----- .../sphinx_book_theme/macros/buttons.html | 4 +- .../theme/sphinx_book_theme/theme.conf | 2 + tests/test_build.py | 48 ++++++ tests/test_build/build__header-article.html | 6 +- .../header__repo-buttons--all-off.html | 6 +- .../header__repo-buttons--all-on.html | 24 +-- .../header__repo-buttons--custom-branch.html | 8 +- .../header__repo-buttons--one-on.html | 8 +- .../header__source-buttons--bitbucket.html | 11 ++ .../header__source-buttons--github.html | 15 ++ .../header__source-buttons--gitlab.html | 11 ++ ...header__source-buttons--gitlab_manual.html | 11 ++ 15 files changed, 309 insertions(+), 94 deletions(-) create mode 100644 tests/test_build/header__source-buttons--bitbucket.html create mode 100644 tests/test_build/header__source-buttons--github.html create mode 100644 tests/test_build/header__source-buttons--gitlab.html create mode 100644 tests/test_build/header__source-buttons--gitlab_manual.html diff --git a/docs/components/source-files.md b/docs/components/source-files.md index 2c0958b7b..5d94930ce 100644 --- a/docs/components/source-files.md +++ b/docs/components/source-files.md @@ -3,78 +3,120 @@ 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`. +- **GitLab**: For example, `https://gitlab.com/gitlab-org/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", ... } ``` -## 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, ... } ``` diff --git a/docs/conf.py b/docs/conf.py index 7ce96e3a2..ee68cb1cf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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, diff --git a/src/sphinx_book_theme/header_buttons/__init__.py b/src/sphinx_book_theme/header_buttons/__init__.py index d1b7247ef..eac9f6bc7 100644 --- a/src/sphinx_book_theme/header_buttons/__init__.py +++ b/src/sphinx_book_theme/header_buttons/__init__.py @@ -1,8 +1,11 @@ """Generate metadata for header buttons.""" - from sphinx.errors import SphinxError from sphinx.locale import get_translation +from pydata_sphinx_theme import _get_theme_options, _config_provided_by_user +from sphinx.util import logging + +LOGGER = logging.getLogger(__name__) MESSAGE_CATALOG_NAME = "booktheme" translation = get_translation(MESSAGE_CATALOG_NAME) @@ -22,10 +25,59 @@ def _as_bool(var): return False -def _config_provided_by_user(app, key): - """Check if the user has manually provided the config.""" - # TODO: Remove this when we bump pydata to the latest version and import from there. - return any(key in ii for ii in [app.config.overrides, app.config._raw_config]) +def _update_context_with_repository_info(opts, context): + """Use the pydata theme to get the "edit this page" link.""" + # Check for manually given options first + repo_url = opts.get("repository_url", "") + branch = opts.get("repository_branch", "") + provider = opts.get("repository_provider", "") + relpath = opts.get("path_to_docs", "") + if branch == "": + branch = "main" + + # We assume the final two parts of the repository URL are the org/repo + parts = repo_url.strip("/").split("/") + org, repo = parts[-2:] + + # Infer the provider if it wasn't manually given + provider_url = "" + if provider == "": + # We assume the provider URL is all of the parts that come before org/repo + provider_url = "/".join(parts[:-2]) + for iprov in ["github", "gitlab", "bitbucket"]: + if iprov in provider_url.lower(): + provider = iprov + break + + # If provider is still empty, raise an error because we don't recognize it + if provider == "": + raise SphinxError(f"Provider not recognized in repository url {repo_url}") + + # Update the context because this is what the get_edit_url function uses. + repository_information = { + f"{provider}_user": org, + f"{provider}_repo": repo, + f"{provider}_version": branch, + "doc_path": relpath, + } + + # In case a self-hosted GitLab or BitBucket instance is used + if provider_url != "": + repository_information[f"{provider}_url"] = provider_url + context.update(repository_information) + + +def _get_repo_url(context): + """Return the provider URL based on what is defined in context.""" + for provider in ["github", "bitbucket", "gitlab"]: + if f"{provider.lower()}_url" in context: + source_user = f"{provider.lower()}_user" + source_repo = f"{provider.lower()}_repo" + provider_url = f"{provider.lower()}_url" + repo_url = ( + f"{context[provider_url]}/{context[source_user]}/{context[source_repo]}" + ) + return repo_url, provider def prep_header_buttons(app, pagename, templatename, context, doctree): @@ -35,7 +87,7 @@ def prep_header_buttons(app, pagename, templatename, context, doctree): def add_header_buttons(app, pagename, templatename, context, doctree): """Populate the context with header button metadata we'll insert in templates.""" - opts = app.builder.theme_options + opts = _get_theme_options(app) pathto = context["pathto"] header_buttons = context["header_buttons"] @@ -50,6 +102,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "javascript": "toggleFullScreen()", "tooltip": translation("Fullscreen mode"), "icon": "fas fa-expand", + "label": "fullscreen-button", } ) @@ -58,79 +111,97 @@ def add_header_buttons(app, pagename, templatename, context, doctree): # For some reason the source_suffix sometimes isn't there even when doctree is repo_keywords = [ "use_issues_button", + "use_source_button", "use_edit_page_button", "use_repository_button", ] for key in repo_keywords: opts[key] = _as_bool(opts.get(key)) + # Update pydata `html_context` options by inferring them from `repository_url` + if "repository_url" in opts: + _update_context_with_repository_info(opts, context) + + # Create source buttons for any that are enabled if any(opts.get(kw) for kw in repo_keywords): - repo_url = opts.get("repository_url", "") - if not repo_url: - raise SphinxError( - "Repository buttons enabled, but repository_url not given. " - "Please add a repository_url." - ) + # Loop through the possible buttons and construct+add their URL repo_buttons = [] if opts.get("use_repository_button"): + repo_url, provider = _get_repo_url(context) + repo_buttons.append( { "type": "link", "url": repo_url, "tooltip": translation("Source repository"), - "text": "repository", - "icon": "fab fa-github", + "text": "Repository", + "icon": f"fab fa-{provider.lower()}", + "label": "source-repository-button", } ) - if opts.get("use_issues_button"): + if opts.get("use_source_button") and doctree and suff: + # We'll re-use this to make action-specific URLs + provider, edit_url = context["get_edit_provider_and_url"]() + # Convert URL to a blob so it's for viewing + if provider.lower() == "github": + # Use plain=1 to ensure the source text is shown, not rendered + source_url = edit_url.replace("/edit/", "/blob/") + "?plain=1" + elif provider.lower() == "gitlab": + source_url = edit_url.replace("/edit/", "/blob/") + elif provider.lower() == "bitbucket": + source_url = edit_url.replace("?mode=edit", "") + repo_buttons.append( { "type": "link", - "url": f"{repo_url}/issues/new?title=Issue%20on%20page%20%2F{context['pagename']}.html&body=Your%20issue%20content%20here.", # noqa: E501 - "text": translation("open issue"), - "tooltip": translation("Open an issue"), - "icon": "fas fa-lightbulb", + "url": source_url, + "tooltip": translation("Show source"), + "text": translation("Show source"), + "icon": "fas fa-code", + "label": "source-file-button", } ) if opts.get("use_edit_page_button") and doctree and suff: - branch = opts.get("repository_branch", "") - if branch == "": - branch = "master" - relpath = opts.get("path_to_docs", "") - org, repo = repo_url.strip("/").split("/")[-2:] - - # Update the context because this is what the get_edit_url function uses. - context.update( - { - "github_user": org, - "github_repo": repo, - "github_version": branch, - "doc_path": relpath, - } - ) - - provider, url = context["get_edit_provider_and_url"]() + # We'll re-use this to make action-specific URLs + provider, edit_url = context["get_edit_provider_and_url"]() repo_buttons.append( { "type": "link", - "url": url, - "tooltip": translation("Edit on") + f"{provider}", - "text": translation("suggest edit"), + "url": edit_url, + "tooltip": translation("Suggest edit"), + "text": translation("Suggest edit"), "icon": "fas fa-pencil-alt", + "label": "source-edit-button", } ) + if opts.get("use_issues_button"): + repo_url, provider = _get_repo_url(context) + if "github.com" not in repo_url: + LOGGER.warn(f"Open issue button not yet supported for {provider}") + else: + repo_buttons.append( + { + "type": "link", + "url": f"{repo_url}/issues/new?title=Issue%20on%20page%20%2F{context['pagename']}.html&body=Your%20issue%20content%20here.", # noqa: E501 + "text": translation("Open issue"), + "tooltip": translation("Open an issue"), + "icon": "fas fa-lightbulb", + "label": "source-issues-button", + } + ) + # If we have multiple repo buttons enabled, add a group, otherwise just 1 button if len(repo_buttons) > 1: header_buttons.append( { "type": "group", "tooltip": translation("Source repositories"), - "icon": "fab fa-github", + "icon": f"fab fa-{provider.lower()}", "buttons": repo_buttons, - "label": "repository-buttons", + "label": "source-buttons", } ) elif len(repo_buttons) == 1: @@ -151,6 +222,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "text": ".ipynb", "icon": "fas fa-code", "tooltip": translation("Download notebook file"), + "label": "download-notebook-button", } ) @@ -162,6 +234,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "text": suff, "tooltip": translation("Download source file"), "icon": "fas fa-file", + "label": "download-source-button", } ) download_buttons.append( @@ -171,6 +244,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "text": ".pdf", "tooltip": translation("Print to PDF"), "icon": "fas fa-file-pdf", + "label": "download-pdf-button", } ) diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html b/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html index 5cbc2b5d4..c61868d0d 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html @@ -36,10 +36,10 @@ {% endmacro %} -{% macro render_button_group(buttons, icon, tooltip=None, label=None) %} +{% macro render_button_group(buttons, icon, tooltip=None, label=None, classes="") %} {# A bootstrap dropdown #} {# Bootstrap dropdown ref: https://getbootstrap.com/docs/5.2/components/dropdowns/ #} -
+
diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf b/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf index e5428112a..272406474 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf @@ -18,6 +18,7 @@ article_header_end = article-header-buttons.html use_download_button = True use_fullscreen_button = True use_issues_button = False +use_source_button = False use_repository_button = False # Note: We also inherit use_edit_page_button from the PyData theme @@ -25,6 +26,7 @@ use_repository_button = False path_to_docs = repository_url = repository_branch = +repository_provider = launch_buttons = {} # Header / navbar. diff --git a/tests/test_build.py b/tests/test_build.py index 6023a714c..5bcd121bc 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -202,6 +202,54 @@ def test_header_repository_buttons( ) +@pytest.mark.parametrize( + "provider, repo", + [ + ("", "https://github.com/executablebooks/sphinx-book-theme"), + ("", "https://gitlab.com/gitlab-org/gitlab"), + ("", "https://opensource.ncsa.illinois.edu/bitbucket/scm/u3d/3dutilities"), + ("gitlab", "https://mywebsite.com/gitlab/gitlab-org/gitlab"), + ], +) +def test_source_button_url(sphinx_build_factory, file_regression, provider, repo): + """Test that source button URLs are properly constructed.""" + # All buttons on + use_issues = "github.com" in repo + confoverrides = { + "html_theme_options": { + "repository_url": repo, + "use_repository_button": True, + "use_edit_page_button": True, + "use_source_button": True, + "use_issues_button": use_issues, + } + } + if provider == "": + provider = [ii for ii in ["github", "gitlab", "bitbucket"] if ii in repo][0] + else: + provider += "_manual" + + sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build( + assert_pass=True + ) + # Check that link of each button is correct, and that the icon has right provider + links = sphinx_build.html_tree("section1", "ntbk.html").select( + ".dropdown-source-buttons .dropdown-menu a" + ) + icons = sphinx_build.html_tree("section1", "ntbk.html").select( + ".dropdown-source-buttons .dropdown-menu i" + ) + links = [ii["href"] for ii in links] + icons = [ii.prettify() for ii in icons] + check = "\n".join(["\n".join(ii) for ii in zip(links, icons)]) + file_regression.check( + check, + basename=f"header__source-buttons--{provider}", + extension=".html", + encoding="utf8", + ) + + def test_header_launchbtns(sphinx_build_factory, file_regression): """Test launch buttons.""" sphinx_build = sphinx_build_factory("base").build(assert_pass=True) diff --git a/tests/test_build/build__header-article.html b/tests/test_build/build__header-article.html index c81dbc342..bb230b1ef 100644 --- a/tests/test_build/build__header-article.html +++ b/tests/test_build/build__header-article.html @@ -70,7 +70,7 @@
-
  • - + @@ -94,7 +94,7 @@
  • -
    • - + @@ -25,7 +25,7 @@
    • - -
      +
      - - + @@ -38,7 +38,7 @@
      • - + @@ -49,7 +49,7 @@
      • - - + @@ -20,7 +20,7 @@
        • - + @@ -31,7 +31,7 @@
        • -
      -
+