Skip to content

Commit

Permalink
Fix extra whitespace in sidebars (#1115)
Browse files Browse the repository at this point in the history
* Fix extra whitespace in sidebars

* Searchbox

* Update src/pydata_sphinx_theme/__init__.py

Co-authored-by: Daniel McCloy <dan@mccloy.info>

* make test pass

* Fix template filter to remove empty files

* ABlog in template test

* Move clear search button to primary sidebar

* Move search clear button to top of article

Co-authored-by: Daniel McCloy <dan@mccloy.info>
  • Loading branch information
choldgraf and drammock authored Jan 13, 2023
1 parent 30a0b34 commit aacaac3
Show file tree
Hide file tree
Showing 13 changed files with 113 additions and 54 deletions.
16 changes: 8 additions & 8 deletions docs/_static/contributors.yaml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion docs/scripts/generate_collaborators_gallery.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
}
)

Expand Down
11 changes: 4 additions & 7 deletions docs/user_guide/source-buttons.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
15 changes: 11 additions & 4 deletions noxfile.py
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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]")
Expand All @@ -37,13 +44,15 @@ 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")


@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]")
Expand All @@ -52,17 +61,15 @@ 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)


@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
Expand Down
27 changes: 22 additions & 5 deletions src/pydata_sphinx_theme/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [
Expand All @@ -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`
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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
Expand Down
50 changes: 50 additions & 0 deletions src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss
Original file line number Diff line number Diff line change
@@ -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;
}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
}
}
}
6 changes: 2 additions & 4 deletions src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -93,6 +89,8 @@
<div class="bd-header-article">{% include "sections/header-article.html" %}</div>
{# Article content #}
{% block docs_body %}
{# This is empty and only shows up if text has been highlighted by the URL #}
{% include "components/searchbox.html" %}
<article class="bd-article" role="main">
{% block body %}{% endblock %}
</article>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ navbar_persistent = search-button.html
header_links_before_dropdown = 5
primary_sidebar_end = sidebar-ethical-ads.html
footer_items = copyright.html, theme-version.html, sphinx-version.html
secondary_sidebar_items = page-toc.html, searchbox.html, edit-this-page.html, sourcelink.html
secondary_sidebar_items = page-toc.html, edit-this-page.html, sourcelink.html
switcher =
check_switcher = True
pygment_light_style = a11y-high-contrast-light
Expand Down
1 change: 0 additions & 1 deletion tests/sites/deprecated/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@
"logo_text": "DOCS",
"page_sidebar_items": [
"page-toc.html",
"searchbox.html",
"edit-this-page.html",
"sourcelink.html",
],
Expand Down
14 changes: 13 additions & 1 deletion tests/test_build.py
Original file line number Diff line number Diff line change
Expand Up @@ -541,7 +541,7 @@ def test_edit_page_url(sphinx_build_factory, html_context, edit_url):
sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides)

if edit_url is None:
with pytest.raises(sphinx.errors.ThemeError):
with pytest.raises(sphinx.errors.ExtensionError):
sphinx_build.build()
return

Expand Down Expand Up @@ -765,6 +765,8 @@ def test_deprecated_build_html(sphinx_build_factory, file_regression):
file_regression.check(navbar.prettify(), basename="navbar_ix", extension=".html")

# Sidebar subpage
# This re-uses the same HTML template used above (w/o deprecated config)
# because they should still be the same.
sidebar = subpage_html.select(".bd-sidebar")[0]
file_regression.check(
sidebar.prettify(), basename="sidebar_subpage", extension=".html"
Expand All @@ -783,3 +785,13 @@ def test_ablog(sphinx_build_factory):
confoverrides = {"extensions": ["ablog"]}
sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
assert sphinx_build.app.config.fontawesome_included is True


def test_empty_templates(sphinx_build_factory):
"""If a template is empty (e.g., via a config), it should be removed."""
# When configured to be gone, the template should be removed w/ its parent.
# ABlog needs to be added so we can test that template rendering works w/ it.
confoverrides = {"html_show_sourcelink": False, "extensions": ["ablog"]}
sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
toc_items = sphinx_build.html_tree("page1.html").select(".toc-item")
assert not any(ii.select(".tocsection.sourcelink") for ii in toc_items)
2 changes: 0 additions & 2 deletions tests/test_build/sidebar_subpage.html
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,6 @@
</div>
</div>
<div class="sidebar-end-items sidebar-primary__section">
<div class="sidebar-end-items__item">
</div>
</div>
<div id="rtd-footer-container">
</div>
Expand Down

0 comments on commit aacaac3

Please sign in to comment.