diff --git a/docs/_static/contributors.yaml b/docs/_static/contributors.yaml index 11b773ef3..229e469ff 100644 --- a/docs/_static/contributors.yaml +++ b/docs/_static/contributors.yaml @@ -1,24 +1,24 @@ - header: "@bollwyvl" image: https://avatars.githubusercontent.com/u/45380 - link: https://github.com/bollwyvl + website: https://github.com/bollwyvl - header: "@jarrodmillman" image: https://avatars.githubusercontent.com/u/123428 - link: https://github.com/jarrodmillman + website: https://github.com/jarrodmillman - header: "@hoetmaaiers" image: https://avatars.githubusercontent.com/u/468045 - link: https://github.com/hoetmaaiers + website: https://github.com/hoetmaaiers - header: "@jorisvandenbossche" image: https://avatars.githubusercontent.com/u/1020496 - link: https://github.com/jorisvandenbossche + website: https://github.com/jorisvandenbossche - header: "@damianavila" image: https://avatars.githubusercontent.com/u/1640669 - link: https://github.com/damianavila + website: https://github.com/damianavila - header: "@drammock" image: https://avatars.githubusercontent.com/u/1810515 - link: https://github.com/drammock + website: https://github.com/drammock - header: "@choldgraf" image: https://avatars.githubusercontent.com/u/1839645 - link: https://github.com/choldgraf + website: https://github.com/choldgraf - header: "@12rambau" image: https://avatars.githubusercontent.com/u/12596392 - link: https://github.com/12rambau + website: https://github.com/12rambau diff --git a/docs/scripts/generate_collaborators_gallery.py b/docs/scripts/generate_collaborators_gallery.py index 52ffb9175..d0437cc39 100644 --- a/docs/scripts/generate_collaborators_gallery.py +++ b/docs/scripts/generate_collaborators_gallery.py @@ -22,7 +22,7 @@ { "header": f"@{collaborator['login']}", "image": f"https://avatars.githubusercontent.com/u/{collaborator['id']}", - "link": collaborator["html_url"], + "website": collaborator["html_url"], } ) diff --git a/docs/user_guide/source-buttons.rst b/docs/user_guide/source-buttons.rst index 2d914c0ff..16bfe2ace 100644 --- a/docs/user_guide/source-buttons.rst +++ b/docs/user_guide/source-buttons.rst @@ -83,13 +83,10 @@ any other context values. View Source link ================ -You can add a button that will direct users to view the source of a page (i.e., the underlying ``reStructuredText`` or ``MyST Markdown`` for the page). -To do so, add the following extension to your documentation: +By default, this theme adds a button link to view the source of a page (i.e., the underlying ``reStructuredText`` or ``MyST Markdown`` for the page). +To disable it, use the following configuration: + .. code-block:: python - extensions = [ - ... - "sphinx.ext.viewcode", - ... - ] + html_show_sourcelink = False diff --git a/noxfile.py b/noxfile.py index 94038e677..3bf851833 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,3 +1,9 @@ +"""Automatically build our documentation or run tests. + +Environments are re-used by default. Use the following-pattern to re-install them. + +nox -s docs -- -r +""" import nox from pathlib import Path @@ -29,6 +35,7 @@ def _should_install(session): @nox.session def compile(session): + """Compile the theme's web assets with sphinx-theme-builder.""" if _should_install(session): session.install("-e", ".") session.install("sphinx-theme-builder[cli]") @@ -37,6 +44,7 @@ def compile(session): @nox.session def docs(session): + """Build the documentation and place in docs/_build/html.""" if _should_install(session): session.install("-e", ".[doc]") session.run("sphinx-build", "-b=html", "docs/", "docs/_build/html") @@ -44,6 +52,7 @@ def docs(session): @nox.session(name="docs-live") def docs_live(session): + """Build the docs with a live server that re-loads as you make changes.""" if _should_install(session): session.install("-e", ".[doc]") session.install("sphinx-theme-builder[cli]") @@ -52,6 +61,7 @@ def docs_live(session): @nox.session(name="test") def test(session): + """Run the test suite. Use `-- -r` to re-build the environment.""" if _should_install(session): session.install("-e", ".[test]") session.run("pytest", *session.posargs) @@ -59,10 +69,7 @@ def test(session): @nox.session(name="profile") def profile(session): - """Generate a profile chart with py-spy. - - The chart will be placed at profile.svg and can be viewed in the browser. - """ + """Generate a profile chart with py-spy. The chart will be placed at profile.svg.""" import shutil as sh import tempfile from textwrap import dedent diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 7a943de33..d2b00101c 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -192,7 +192,7 @@ def prepare_html_config(app, pagename, templatename, context, doctree): context["theme_version"] = __version__ -def update_templates(app, pagename, templatename, context, doctree): +def update_and_remove_templates(app, pagename, templatename, context, doctree): """Update template names and assets for page build.""" # Allow for more flexibility in template names template_sections = [ @@ -218,6 +218,20 @@ def update_templates(app, pagename, templatename, context, doctree): if not os.path.splitext(template)[1]: context[section][ii] = template + ".html" + # If this is the page TOC, check if it is empty and remove it if so + def _remove_empty_templates(tname): + # These templates take too long to render, so skip them. + # They should never be empty anyway. + SKIP_EMPTY_TEMPLATE_CHECKS = ["sidebar-nav-bs.html", "navbar-nav.html"] + if not any(tname.endswith(temp) for temp in SKIP_EMPTY_TEMPLATE_CHECKS): + # Render the template and see if it is totally empty + rendered = app.builder.templates.render(tname, context) + if len(rendered.strip()) == 0: + return False + return True + + context[section] = list(filter(_remove_empty_templates, context[section])) + # Remove a duplicate entry of the theme CSS. This is because it is in both: # - theme.conf # - manually linked in `webpack-macros.html` @@ -902,9 +916,12 @@ def _overwrite_pygments_css(app, exception=None): # see if user specified a light/dark pygments theme, if not, use the # one we set in theme.conf style_key = f"pygment_{light_or_dark}_style" - theme_name = app.config.html_theme_options.get( - style_key, app.builder.globalcontext.get(f"theme_{style_key}") - ) + + # globalcontext sometimes doesn't exist so this ensures we do not error + theme_name = app.config.html_theme_options.get(style_key, None) + if theme_name is None and hasattr(app.builder, "globalcontext"): + theme_name = app.builder.globalcontext.get(f"theme_{style_key}") + # make sure we can load the style if theme_name not in pygments_styles: logger.warning( @@ -1051,8 +1068,8 @@ def setup(app): app.connect("builder-inited", update_config) app.connect("html-page-context", setup_edit_url) app.connect("html-page-context", add_toctree_functions) - app.connect("html-page-context", update_templates) app.connect("html-page-context", prepare_html_config) + app.connect("html-page-context", update_and_remove_templates) app.connect("build-finished", _overwrite_pygments_css) # Include component templates diff --git a/src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss b/src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss new file mode 100644 index 000000000..fd8aa8223 --- /dev/null +++ b/src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss @@ -0,0 +1,50 @@ +/** + * The 'Hide Search Matches' button. + * This only shows up when a person lands on a page after clicking a search result. + * Clicking it removes the highlighting of the search term from the page. + * We want it to behave like a button. + */ +div#searchbox { + // Leave `#searchbox` rules empty so that it doesn't show at all when it is empty + p.highlight-link { + margin: 1rem 0; + width: fit-content; + + // A bit more margin on wide screens to mimic article behavior + @include media-breakpoint-up($breakpoint-sidebar-secondary) { + margin-left: 2rem; + } + + // Put outer shadow on this one so that we can darken the link w/ an inner shadow + @include box-shadow(); + + // Style the button to look like a Sphinx Design button + a { + border-radius: 0.25rem; + font-size: 1.25rem; + padding: 0.75rem; + background-color: var(--pst-color-primary); + // Button text is always white with Sphinx Design buttons + color: white; + + // The box shadow is inset so that it darkens the button on hover + transition: box-shadow 0.25s ease-out; + &:hover { + box-shadow: inset 0px 0px 50px 50px rgba(0, 0, 0, 0.25); + + // Remove underline for link + text-decoration: none; + } + + // add icon via CSS because the link is created by javascript + // match padding to .toc-item > i above + &:before { + content: var(--pst-icon-search-minus); + color: unset; + font-family: "Font Awesome 6 Free"; + font-weight: 900; + margin-right: 0.5rem; + } + } + } +} diff --git a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss b/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss index 46ca52ea9..5de6eea20 100644 --- a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss +++ b/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss @@ -37,6 +37,7 @@ @import "./components/navbar-links"; @import "./components/prev-next"; @import "./components/search"; +@import "./components/searchbox"; @import "./components/switcher-theme"; @import "./components/switcher-version"; @import "./components/toc-inpage"; diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss index 0deb9de0f..c604accc2 100644 --- a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss +++ b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss @@ -53,23 +53,3 @@ padding-left: 1rem; } } - -// The 'Hide Search Matches' link -div#searchbox { - p.highlight-link { - // remove excess margin from p tag - margin-bottom: 0px; - a { - // add icon via CSS because the link is created by javascript - // match padding to .toc-item > i above - &:before { - content: var(--pst-icon-search-minus); - color: unset; // make sure it uses the same color as the text - font-family: "Font Awesome 6 Free"; - font-weight: 900; - padding-right: 0.5rem; - margin-right: 0; - } - } - } -} diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html index b57d142e1..5c10712c7 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html @@ -13,10 +13,6 @@ {% if sidebar_nav_html | length == 0 %} {% set sidebars = sidebars | reject("in", "sidebar-nav-bs.html") | list %} {% endif %} -{# Remove the page-toc from secondary sidebar if there are no links to show #} -{% if generate_toc_html() | length == 0 %} - {% set theme_secondary_sidebar_items = theme_secondary_sidebar_items | reject("in", "page-toc.html") | list %} -{% endif %} {# A flag for whether we include a secondary sidebar based on the page metadata #} {% set remove_sidebar_secondary = (meta is defined and meta is not none and 'html_theme.sidebar_secondary.remove' in meta) @@ -93,6 +89,8 @@