Clean-up CSS classes for the custom elements (sidebars, toc items, ..)

[jorisvandenbossche]

Right now, the layout and CSS is a bit a mess, as a consequence of copy pasting things (eg from the bootstrap docs) to minimally "get things working". But so there are a few CSS classes (like bd-links, bd-toc-items, bd-sidenav, section-nav, nav-item, toc-entry, ...) of which there are at least some redundant.

We should also try to define a consistent terminology:

• consistent prefix scheme (the bd- is coming from the "bootstrap docs", we could maybe rename this to bs- of "bootstrap-sphinx")
• consistent names for the left sidebar ("sidebar", "sidenav", ..) and the right sidebar ("toc", "toc-nav", ..)

[12rambau]

closed by #662 ?

[choldgraf]

To me the main question is if we want to keep bd- or if we want to switch that class prefix. That'll be a big breaking change, but might be a good opportunity to standardize around this theme's branding. What do you think? I'm not super opinionated...

But either way, we should document the use of this prefix, and the standardization on the sphinx-basic-ng naming, and consider this issue closed once we agree there

[stefanv]

Hi all, we've started using the PDST CSS in the Scientific Python Hugo Theme, in an effort to better align the themes and to utilize the accessibility work done here.

Our sites are generated using a different toolchain (hugo + chroma, instead of sphinx + pygments), and as such our DOM also differs significantly.

For us, it would be very helpful to (a) have class names be mapped to PDST concepts (vs bootstrap-doc theme or other designs) and (b) to have pdst- or some other sensible prefix.

Would it be possible to agree on a prefix/naming scheme for this theme and to apply it throughout? I'd be happy to help out with such an effort.

[12rambau]

I think we are slowly moving toward this objective. We clearly decided to use the pst- prefix in our css for example in the colors. It is a big effort to track down all the remaining bootstrap prefixed elements and that's mainly why it's on stale for so long. If you have time to dedicate building a PR (even partial) I would be more than happy to review it.

That will be one step toward a first stable release of this theme.

[stefanv]

Excellent, thanks @12rambau. And, to be clear, the goal, for now, would simply be to replace bd- with pdst-, or should there also be renaming to PDST terminology?

[12rambau]

Be careful we use "pst" without the "d" like in the logo. And I guess yes that would be a very good first step. Note that many things have moved since this issue was opened and some of the names have already been replaced

[choldgraf]

Just noting that some kind of deprecation pathway at the least would be helpful here. Anybody that has special-cased CSS classes using the bd- prefix, or any downstream themes like the book theme, will likely be broken as soon as the bd- classes are removed.

[stefanv]

Thanks, Chris. I'll see how easy it is to add aliases first.