docs: strip out custom theming and use stock RTD #5191
Conversation
|
When approved, I will immediately backport this to maint branches and update the system doing the automated builds to Debian bookworm's default sphinx. |
|
Woo, with these changes, the site also builds nicely in Sphinx v8, which we'll get on Trixie next year. (We could use a special-purpose site builder image for that now, but I don't think we need anything new.) |
|
Forgot to comment on this in my earlier review because it didn't come up in the diff:
We'll need a configure check for this then, like we have for pod::pom:view::restructured and the other doc build dependencies. |
|
Can you rebase this on current upstream master? Since there's a bunch of doc changes on master following the 3.12 fork, and there might be stuff in my changes that'll warn/etc with newer sphinx. |
rjbs
force-pushed
the
cyr-1472-strip-custom-sphinx-theme
branch
from
2459b11 to
49ffde2
Compare
ellie agreed to do this, for which I've made a separate issue. |
|
The level of approval here was unclear (to me), but I've addressed a few things and asked @wolfsage to give another round of review to keep this moving. I'll catch up with you later so we can make sure we're both happy. |
|
The commit "docs: strip out custom theming and use stock RTD" doesn't say why we're doing this - what's the reason to drop the custom theme? |
|
Seems good! It makes search work again (who knew it was broken?!) I don't love the yellow background of code blocks or the pages only taking up half of my wide screen vs the old style, but I can live with it |
This means that the box building the docs will require python3-sphinx-rtd-theme (or however else you get that theme). Why? Because we don't want to keep having to figure out how our custom theming broke across a Sphinx upgrade!
This eliminates warnings about Sphinx 6 strictly requiring exactly one %s in each of the link and text. Zero is not acceptable.
Glossary entries are global, so should only appear once throughout.
These sections were definition lists, but are not really global glossary entries.
HBA is already defined in the glossary, and should not be duplicated here.
Weirdly, not only were these redundant, but they were wrong in context! This document is about server aggregation with murder, but the glossary component said the frontend was the user interface, instead of the frontend server.
The rc1 and rc2 release notes reused a label for the beta.
The existing globbing had too many overly-specific cases.
This led to quite a few documents having globs that matched nothing,
like:
x/?.?.??
Unless there was a 3.5.10, this would match nothing. Given how we
structure these documents, `x/*` is enough. I've left the `x/*-alpha`
type patterns in place, just to keep the ordering a little nicer, for
now.
This is just the previous commit's work, carried out for v3.12 and v3.13, which didn't exist on this branch until I rebased.
rjbs
force-pushed
the
cyr-1472-strip-custom-sphinx-theme
branch
from
49ffde2 to
3f7139a
Compare
This means that the box building the docs will require python3-sphinx-rtd-theme (or however else you get that theme).
Update: Okay, I got a little carried away here, but I've got the docs building clean, with no errors or warnings. This makes life better because any new warning or error is now worth looking at. Also, this might get us ready to use Sphinx v8, which will be in Debian Trixie, likely out in mid-2025.