DOC: update pydata-sphinx theme

[tupui]

This is a provision for the next release of the PyData Sphinx Theme which should happen in the following days (RC2 already up).

This will be needed if the doc is build after 0.10 is released otherwise there will be no search bar. The new search bar is a way better experience. Overall the new version provides a lot of improvements.

[mdhaber]

@tupui tried to resolve merge conflicts. Hope I did it correctly. (Oops, probably shouldn't have skipped CI. )

[tupui]

Thanks Matt for having a look and catching the lint issue 👍 (for the rest we need to wait for the release of the theme.)

[melissawm]

13 mins! And it looks like the warnings are safe. We probably need to add a filter to silence the "theme is not parallel safe" warning, but that seems to be the only issue 🙏

[tupui]

Just for fun, I clicked on the "Explain this error" with AI 🤣 Looks like Sphinx is still too hard for a LLM

[tupui]

@drammock I will have to test locally but online, the sidebar is still off I am afraid. The build time is good though 😃 Was there another PR you wanted to make on this branch?

[h-vetinari]

I will have to test locally but online, the sidebar is still off I am afraid.

It's sidebar and top bar, it seems. I.e. clicking on the "API reference" tab on the top still shows "Development" tab being highlighted (matching the content of the left sidebar).

[tupui]

Yes, same as current deployment.

[drammock]

Argh, ok. I'll try to look again tomorrow.

[drammock]

• make sure that pydata-sphinx-theme 0.15.2 is actually getting installed into CircleCI environment (no "show installed versions" step in CircleCI, but the rendered doc says 0.15.2 in the footer, so we can be fairly sure)
• check if sphinx version matters. CircleCI logs say it was built with Sphinx 5.3.0; my local tests from before were using Sphinx 7.2.6.
  • Local tests can't replicate problem in CIs. Building docs in an env based on the repo's environment.yml (which uses Sphinx 5.3.0) but with pydata theme updated to 0.15.2, using python dev.py --no-build doc --no-cache -jN, I see the correct sidebar on API pages regardless of building with -j1, -j2, or -j8. Not sure what to try next 😞

[tupui]

@drammock if building locally leads to all sidebars etc being ok. Then I think we are good. We can only know for sure once we deploy for real but it might just be again the same issue we have right now with our current dev doc.

[drammock]

@drammock if building locally leads to all sidebars etc being ok. Then I think we are good. We can only know for sure once we deploy for real but it might just be again the same issue we have right now with our current dev doc.

in that case I guess to get the CircleCI build to "pass" you need to somehow make it OK/expected to see

WARNING: the pydata_sphinx_theme extension is not safe for parallel writing
WARNING: doing serial write

... or else stop running CircleCI with -j2

[tupui]

@drammock thank you. For now let's try with removing -j2 because IIUC the warning is a log and would need to write a filter on an event handler.

Otherwise I had the chance to run this locally and it seems all good.

@h-vetinari it would be helpful if you had time to confirm this too. And if everything is fine (and CI comes back green), I would suggest to move this forward.

[h-vetinari]

@h-vetinari it would be helpful if you had time to confirm this too.

So far everything I've done was check the docs as rendered by CI (though IMO this is also the closest we're going to get in advance to what the actual deployment will look like), and with the latest change, the rendered docs look fine AFAICT.

Given the behaviour observed by @drammock, it seems pretty clear that the -j2 is the culprit, given the lack of thread-safety of PST?

And if everything is fine (and CI comes back green), I would suggest to move this forward.

Fine by me to move forward with this and merge, though given the current 42 commits¹, I think we should either squash, or clean up the git history.

Footnotes

1. the answer to life, the universe and everything! ↩

[tupui]

@h-vetinari I am fine with a squash 👍

(In general I am a partisan of squash merge either way 😉)

[drammock]

Squash is fine with me, FWIW. I'll keep looking into why it wasn't enough to just mark the theme as parallel write unsafe... But that shouldn't hold up things here.

[h-vetinari]

Thanks for sticking through this slog @tupui, and for the help @drammock!

[tupui]

Thank you all for your help and dedication! This is great that we can finally move forward and be in sync with the theme.

@tylerjereddy would it be possible for you to re-publish the doc for 1.12 with this?

[h-vetinari]

@tylerjereddy would it be possible for you to re-publish the doc for 1.12 with this?

Let's just merge this and backport it, then it'll automatically show up for 1.12.1 at the latest anyway.

(FWIW, I only didn't push the button yet because I don't want to write the commit message resp. filter/condense the one proposed by github - I feel that's better handled by the author in this case)

[tupui]

@h-vetinari Please feel free to merge. For the message I don't think we need much more than saying we updated the theme. No need to talk about all the commits in the squash. The only important thing to me is to keep the co-author mentions.

[tylerjereddy]

make dist seems to succeed on this branch, so that's a good sign for the release process

If 1.13.0 comes out before 1.12.1 I don't know how much effort backporting is worth, but keeping the label for now seems "ok."