✨ Release candidate ✨ v1.0.0

[choldgraf]

Try out the release candidate for this theme here:

https://github.com/executablebooks/sphinx-book-theme/releases/tag/v1.0.0rc1

Install with

pip install -U --pre sphinx-book-theme

If you see anything wrong, open an issue and cross-link it here! (or just comment if you wish)

This one makes a number of breaking changes, so I'm bumping the major version (see #670 which this will close when it is released).

[mathbunnyru]

That's great news!

I've built our docs with a new version and in general, they look amazing I love the new features and bug fixes.

PR: jupyter/docker-stacks#1855
Docs: https://jupyter-docker-stacks--1855.org.readthedocs.build/en/1855/index.html

I've found some problems I suppose:

1. Wrong content section in the sidebar #545

This issue seems to be back.
https://jupyter-docker-stacks--1855.org.readthedocs.build/en/1855/index.html#contributing

It's impossible to have Contributing section highlighted in the Contents section.

2. The title is missing in the v0.4.0rc1 #671

The title is still missing.
If it is designed to be missing, the blank space above the logo should be decreased slightly.

3. I actually prefer old colors in the bash sections, but that's just my opinion.
   New: https://jupyter-docker-stacks--1855.org.readthedocs.build/en/1855/using/running.html
   Old: https://jupyter-docker-stacks.readthedocs.io/en/latest/using/running.html

4. Last updated on None. at the bottom of each page.
   I don't know how this feature works exactly, so it might not be a bug.

5. If I scroll up, being already on top of the page, on Safari, I see "Skip to main content". I guess this is a feature for mobile devices, but I'm using desktop Safari on macOS.

Let me know if I should reopen issues for 3-5, and please reopen 1-2 if you consider them to be issues.

[choldgraf]

Thanks for these comments @mathbunnyru. I'm responding to feedback and improvements in this PR if you wanna try it out there too.

• ENH: Improvements after v1.0.0rc1 feedback #687

A few responses below

• regarding Wrong content section in the sidebar #545

I tried your link (https://jupyter-docker-stacks--1855.org.readthedocs.build/en/1855/index.html#contributing) and it worked fine for me. The correct section was highlighted. Can you try again and make sure you refresh the page or something to make sure the CSS is loaded?

• regarding the logo title

Here's the behavior:

• If any logo image is set, then you must manually specify HTML logo text in html_theme_options.logo.text

So I suspect that in your case, this is not manually set.

In either case, I've got a PR open that tightens up the whitespace in the sidebar so that the logo has more equal spacing around it if it's text (or an image). Want to give that a shot?

bash coloring

I'm afraid this one we can't easily change. The pygments theme was updated to be more accessibility-friendly. If you want those defaults changed I'd recommend that you open an issue in the pydata theme repository.

If I scroll up, being already on top of the page, on Safari, I see "Skip to main content".

Hmm I am not able to replicate this one. That button should be available only if you hit tab as your first action when you land on a page but it shouldn't be visible (and I can't reveal it) just with a scroll-up action. Can you try in chrome and see if it also happens for you there?

last updated on

I'm not sure why it is None for you, but I opened this PR to remove the template if last_updated is not defined here:

• Add conditional check for last-updated template pydata/pydata-sphinx-theme#1201

[mathbunnyru]

I tried your link (https://jupyter-docker-stacks--1855.org.readthedocs.build/en/1855/index.html#contributing) and it worked fine for me. The correct section was highlighted. Can you try again and make sure you refresh the page or something to make sure the CSS is loaded?

I tried Safari private tab and Vivaldi (Chromium-based browser) and tried to click different parts of content section.
Well, sometimes it works, and sometimes it doesn't.
When I first click "Quick Start" and then "Contributing", it instead tells me I'm reading "Maintainer Help Wanted" section.

If any logo image is set, then you must manually specify HTML logo text in html_theme_options.logo.text

I added it, and it works, thank you 👍

In either case, I've got a PR open that tightens up the whitespace in the sidebar so that the logo has more equal spacing around it if it's text (or an image). Want to give that a shot?

If you could make a new RC release, I will definitely check this.

bash coloring

Ok, I think let's keep the defaults, it's important to be more accessibility-friendly.

last updated on

Great, I think this problem will be gone after a new release.
And I hope we will have this information for our docs, it's quite nice to have.

[choldgraf]

OK I'll make an RC now. I also opened this to track the "skip to content" button issues:

• Theme skip link button is not working on some versions of Safari pydata/pydata-sphinx-theme#1205

FYI it looks like in general, there is different behavior with Safari than with Chrome/Firefox...that might mean it'll take more digging in the future to sort out how to resolve this.

Edit: RC2 is triggered, should be out soon

[mathbunnyru]

Thank you, @choldgraf.
There is less space wasted above the logo, so it looks better know 👍

[PhilipVinc]

I've tried this out. I noticed that for a high-resolution jpg logo in the left sidebar the height: 100% css attribute from pydata makes it so that the logo is stretched vertically...

[choldgraf]

Shit good catch! Can you find a CSS rule that makes it keep the same aspect ratio? I won't be at a computer for a while but am happy to merge a PR!

[PhilipVinc]

Disabling height: 100% works (there is still width :100% ) but I am really not an expert of css so I have no idea if that is a good solution...

Also, that's inherited from pydata-sphinx-theme so the fix should go there?

[choldgraf]

@PhilipVinc i think this should fix it, could you try it out?

• Fix: logo image stretching vertically #689

[martinfleis]

I've noticed that with the RC, the long links in the navbar are wrapped if they are longer than the width of the navbar even if the are "one word" now. See the screenshot from the docs of https://github.com/xarray-contrib/xvec rendered with the stable and with RC.
RC:

stable:

Is there a way to control this? Was it intended? I think that for the API, the old way is much better.

[choldgraf]

hmmm, yep - that change was intentional, because a few other projects had reported it as a bug that the words weren't wrapping and were being cut off. I think it was reported as a bug because, for example, projects with many nested modules might have their entire function names cut off entirely.

Here's the change that modified this, I believe:

https://github.com/pydata/pydata-sphinx-theme/pull/1191/files#diff-138e42ae7155057d1d55db042d39b92a61e05b341948df34d298d1690878006dR43-R44

For now, I suggest that you add a little custom CSS rule that undoes this change if you'd like them to instead be cut off, if we get more reports from others that prefer "cutoff" vs. "word wrap" then we could change it back.

[martinfleis]

Thanks! I'll override it for now. Maybe it may be worth adding an option for that?

[choldgraf]

The tricky thing is that it's hard to add options that control CSS. In the meantime I'll add a note in the CHANGELOG with the rule in case others want to revert it.