Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix extra whitespace in sidebars #1115

Merged
merged 8 commits into from
Jan 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❤️ I did not know this shorcut, I've been using --no-reuse-existing-virtualenvs which is so long to type that it hurts.

"""
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