space icon-links evenly across

[leifwalsh]

(rather than justified left)

fixes #1720

[gabalafou]

Thank you for your interest in making the PyData theme better!

I will need to give this a closer look later, but right now, I'm seeing the icons bunch up because the column-gap rule was removed. Here's a screenshot of the header node when I apply this PR locally and build the docs:

[leifwalsh]

Hmm, that's not what I intended. I'll take a closer look this weekend but let's try putting the column gap back for now.

[leifwalsh]

@gabalafou I think this looks right https://pydata-sphinx-theme--1726.org.readthedocs.build/en/1726/

[drammock]

Looking at the PR build, I see no visible difference versus the docs for current main. @leifwalsh can you confirm that for your project/site this PR still achieves the desired improvement?

In an ideal world we would add a test here that failed on main and passed on this PR; if you can see a clear path to do that please add one... but I'll acknowledge that our tests are not very complete/thorough and testing page layout is tricky to do, so if adding a test is too high a hurdle feel free to say so and we'll move forward without one.

[leifwalsh]

Yeah, I have exactly this in custom css and it works for us:

.navbar-icon-links {
  justify-content: space-evenly;
}

[leifwalsh]

I don't think I've ever tested page layout but I'd be happy to try if you want to point me to an example?

[drammock]

I don't think I've ever tested page layout but I'd be happy to try if you want to point me to an example?

One way is to use Playwright, which loads a headless browser, renders and serves pages (without displaying them anywhere), and lets you interact with the dom. Here's an example from our tests:

pydata-sphinx-theme/tests/test_a11y.py

Lines 227 to 242 in 99f9b1c

	def test_version_switcher_highlighting(page: Page, url_base: str) -> None:
	"""This isn't an a11y test, but needs a served site for Javascript to inject the version menu."""
	page.goto(url=url_base)
	# no need to include_hidden here ↓↓↓, we just need to get the active version name
	button = page.get_by_role("button").filter(has_text="dev")
	active_version_name = button.get_attribute("data-active-version-name")
	# here we do include_hidden, so sidebar & topbar menus should each have a matching entry:
	entries = page.get_by_role("option", include_hidden=True).filter(
	has_text=active_version_name
	)
	assert entries.count() == 2
	# make sure they're highlighted
	for entry in entries.all():
	light_mode = "rgb(10, 125, 145)" # pst-color-primary
	# dark_mode = "rgb(63, 177, 197)"
	expect(entry).to_have_css("color", light_mode)

That test uses expect(locator).to_have_css("color", color_value) and my guess is that .to_have_css(...) may be the best we can do for testing this change; in case I'm wrong, here are the other assertions you might use: https://playwright.dev/python/docs/test-assertions

Another way is to do a static sphinx build on disk (using our test fixture sphinxbuildfactory) and query the resulting BeautifulSoup object:

pydata-sphinx-theme/tests/test_build.py

Lines 218 to 228 in 99f9b1c

	def test_primary_logo_is_dark_when_default_mode_is_dark(sphinx_build_factory) -> None:
	"""Test that the primary logo image is dark when default mode is set to dark."""
	# Ensure no default mode is set
	confoverrides = {
	"html_context": {"default_mode": "dark"},
	}
	sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
	index_html = sphinx_build.html_tree("index.html")
	navbar_brand = index_html.select(".navbar-brand")[0]
	assert navbar_brand.find("img", class_="only-dark") is not None
	assert navbar_brand.find("script", string=re.compile("only-light")) is not None

This latter way is faster but more limited as the page isn't rendered, so you can only really effectively test the page source (not, e.g., the effects of JS).

[leifwalsh]

Hmm, those approaches would really only be testing that CSS works the way CSS is supposed to work, not that it results in output that looks correct.

I'm willing to try if you think it's valuable (e.g. if it would catch a regression somehow) but it doesn't seem super valuable to me. Let me know what you'd like to do, I'll have some hacking time over the weekend.

[drammock]

Hmm, those approaches would really only be testing that CSS works the way CSS is supposed to work, not that it results in output that looks correct.

you're not wrong. I guess the alternative is to use a playwright screenshot and use the file_regression fixture to test that the screenshot image doesn't change. Here's an example of the file_regression fixture:

pydata-sphinx-theme/tests/test_build.py

Lines 329 to 336 in 99f9b1c

	def test_navbar_no_in_page_headers(sphinx_build_factory, file_regression) -> None:
	"""Test navbar elements did not change (regression test)."""
	# https://github.com/pydata/pydata-sphinx-theme/issues/302
	sphinx_build = sphinx_build_factory("test_navbar_no_in_page_headers").build()
	index_html = sphinx_build.html_tree("index.html")
	navbar = index_html.select("ul.bd-navbar-elements")[0]
	file_regression.check(navbar.prettify(), extension=".html")

I don't think we've ever used it for screenshots before though, and the approach feels a bit hackish to me, but I think it's basically the approach used by bespoke website testing frameworks for visual regression testing.

[leifwalsh]

Thanks for that pointer! I'll try it and see if I can get it to do something that won't be really annoying :)

[leifwalsh]

Ok, I don't think that's going to work without a big change to the testing infrastructure. It looks like test_a11y.py is the only place we currently use playwright, and that is only set up to test how the docs for the theme itself (i.e. pydata-sphinx-theme.readthedocs.io) display (and that uses icon-links in the header where they don't expand because there are other flex things to the left). I can add a new docs source tree under tests/sites that uses icon-links in the primary navbar, but that's only set up to test the html output right now, it's not hooked up to playwright.

[drammock]

Ok, I don't think that's going to work without a big change to the testing infrastructure.

Ah yes, my bad! I didn't connect those dots. FWIW we do plan to make such a change to the test infra (rely more on playwright) but this PR is not the right time to try to set that all up.

[leifwalsh]

Thank you! Please ping me if you do get that set up and I'll be happy to add a regression test for this :)