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
561 stars 304 forks source link

DOC - Extensions documentation structure needs improvement #1727

Open trallard opened 4 months ago

trallard commented 4 months ago

Updating this page in the docs made me realize that this part of the docs could really use a restructure:

_Originally posted by @gabalafou in https://github.com/pydata/pydata-sphinx-theme/pull/1721#discussion_r1493108853_

[!NOTE] Opening this issue so we can discuss this organisation proposal as a team @drammock @12rambau @choldgraf and then @gabalafou and I can work on any changes

drammock commented 4 months ago

I like the proposed restructuring. I'd recently noticed the same issue with the "sphinx design" page (but I failed to open an issue about it and promptly forgot). So I'm glad you noticed too and said something.

choldgraf commented 4 months ago

That makes sense to me as well - sounds like this is content that had grown organically and is now in need of some pruning and restructuring. I also think it's helpful to have one page per extension because then there is a source of truth to go to when trying to figure out if the theme is behaving "as expected" since it's often hard to test for theme-specific CSS without just looking at its effects for reference.