Choose approach for base theme
Open
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2
- Forks
- 0
- Avg merge
- 15h 50m
- Merged PRs (30d)
- 12
Description
Description of feature
Concerns:
- Layout: needs to be clean and easy to use, e.g. using simply sphinx toctrees
- Extensions: we need to support MyST notebooks, Sphinx-Design, and maybe more plugins
- Dark mode: has gone through 3 eras, both the theme and plugins need to agree for support (ipywidgets sucks at this). This is the perfect approach: https://github.com/pydata/pydata-sphinx-theme/issues/2484
- Color system: colors shared with the website, available as CSS variables. see pydata theme docs about this.
Ideas:
- customize PyData theme lightly
- customize PyData theme similarly to book theme but being able to fix issues quickly, e.g. https://github.com/executablebooks/sphinx-book-theme/pull/987
- other theme base?
| Theme | Pro | Con |
|---|---|---|
| PyData | Relatively modern CSS makes customization nice: CSS variables, media queries | Looks wonky, header gets big, unclear what belongs into header and what into sidebar[^1] |
| Book | Looks good and clean out of the box, otherwise see PyData (it customizes it) | Slow response to isses, we’d customize a customization, so more complex overrides |
| Other | There might be one that’s perfect? | Most don’t have good notebook/MyST support, might use a dark mode scheme not supported by extensions |
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare the PyData and Sphinx Book theme approaches against the stated requirements for toctrees, MyST notebooks, Sphinx-Design, dark mode, and shared CSS variables. Review the linked theme documentation and issue or pull request, then document a selected base theme and the rationale for that choice.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- design, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100