Opened 6 weeks ago
Last modified 5 days ago
#37138 assigned Cleanup/optimization
Outdated docs CSS in local and preview builds
| Reported by: | Mike Edmunds | Owned by: | Mike Edmunds |
|---|---|---|---|
| Component: | Documentation | Version: | 6.0 |
| Severity: | Normal | Keywords: | |
| Cc: | Triage Stage: | Accepted | |
| Has patch: | yes | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | yes |
| Easy pickings: | no | UI/UX: | no |
Description
The CSS used for documentation in local and ReadTheDocs PR preview builds is significantly different from the CSS used on docs.djangoproject.com.
The styles in docs/_theme/djangodocs/static/djangodocs.css:
- have usability problems (forum discussion)
- are missing semantically-important styles (forum discussion)
- don't support dark mode
These and other differences complicate contributing to the documentation, as you can't really be sure how it's going to look until the PR is merged and published.
We should find a way to replace docs/_theme/djangodocs/static/*.css with the styles from djangoproject.com. (E.g., the result of make compile-scss-debug in that project.)
Change History (3)
comment:1 by , 6 weeks ago
| Triage Stage: | Unreviewed → Accepted |
|---|
comment:2 by , 6 weeks ago
| Has patch: | set |
|---|---|
| Patch needs improvement: | set |
comment:3 by , 5 days ago
Due to concerns about ongoing maintenance for a custom theme (and unclear license status of the djangoproject.com stylesheets), the current proposal is to replace the custom docs/_theme/djangoproject theme with a third-party, well-maintained Sphinx theme such as furo or pydata-sphinx-theme.
Makes sense, I agree this is desired. How to accomplish the goal, it's something I don't see clearly but I'm eager to see options!