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

pydata / pydata-sphinx-theme

A clean, three-column Sphinx theme with Bootstrap for the PyData community

https://pydata-sphinx-theme.readthedocs.io

BSD 3-Clause "New" or "Revised" License

618 stars 321 forks source link

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

Open jorisvandenbossche opened 5 years ago

jorisvandenbossche commented 5 years ago

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 commented 2 years ago

closed by #662 ?

choldgraf commented 2 years ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 12 months ago

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 commented 12 months ago

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 commented 12 months ago

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 commented 12 months ago

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