When running django documentation to preview my changes locally, I spent a fair amount of time thinking something was missing because it looks [like this], but then I asked (Django documentation — Django 5.0.6 documentation) other contributors and they said this is the usual local theme.
I was wondering why this is the case as it added a bit of confusion and it’s usually better to be able to preview things as they’ll finally be rendered in production.
Hoping I can add an explanation about this in the “documentation contribution” guidelines or in the README.md or else, try and make the local theme the same as the official one.
Thanks
1 Like
Hi,
That’s a great question, and I agree that this mismatch is confusing.
I’m not sure I have the whole answer to your question (and there might be multiple “why”-s here), but I think I can shed some light on some aspects at least.
The yellow/green style (which you get when building the docs locally, or - as you pointed out - on ReadTheDocs) is Django’s old official theme. This is how the website used to look like, until it was overhauled about 10 years ago with a new design, which we still have today.
I was on the team that led the implementation of that “new” design, and I have a vague memory that the topic of the local docs theme was mentioned, but that it was decided that the “old” theme would stay.
My recollection is that it had something to do with licensing. I might be wrong here, but the old theme has the same license as Django (being included in the repository alongside the code), whereas the new theme does not have a public license (the DSF owns the rights I think).
Because this has to do with licensing, it might be tricky to change things, but maybe the color palette could be changed at least? Surely that falls within the license requirements (he says, being completely ignorant of licensing laws).
In any case, if you do end up making a pull request to the README, please feel free to tag me if you have questions or want a review (I have the same username on github or in the Django #contributor-discussion channel).
Thanks again for raising this up 
2 Likes
I wanted to raise this again and see if we can find a solution. The CSS mismatch between the production docs site vs. local/preview builds complicates working on the docs. It’s not just color schemes: there are (visual) semantic differences between the two styles. Example below.
If there’s a licensing issue with the DSF owning the docs site styles, I’d think that could be solved somehow. (Do we know anyone at the DSF? 
) Maybe we could vendor the DSF’s CSS into Django’s docs with the DSF’s license intact, like we do for other vendored code (such as docs/_theme/djangodocs/static/fontawesome).
Here’s an example: we want to versionchanged:: two things related to the same function. There’s a bug in my reST source—can you spot it from the local docs build? (I didn’t.)
The mistake becomes visible on the production site: both of those paragraphs were meant to be inside the versionchanged:: directive, but only one is:
I ran into this particular issue in my own recent documentation work. But I’m guessing it’s not the only significant difference between the old and new docs CSS.
[Related aside: The bundled CSS on docs.djangoproject.com is missing a /*! license or copyright comment for DSF’s CSS, making it seem like it’s covered by FontAwesome’s MIT license statement from earlier in the bundle.]
3 Likes
I opened ticket #37138 (Outdated docs CSS in local and preview builds) – Django to have the styles in Django Sphinx builds match the ones on docs.djangoproject.com.
Looking into it a bit, I think the issues may be more technical and content than licensing-related:
- The djangoproject style source is scss, so needs to be compiled to css. We might not want to depend on an scss compiler for Django docs builds. (Or it might be OK? We already have other docs build requirements.)
- The docs-specific styles are mixed in with other djangoproject.com site styles, and it might be difficult to separate them. (See _style.scss. This includes things we’d want, like shared layout and base styles, plus things we don’t need, like fundraising and hero modules. But maybe that extra CSS is OK for now to get styles matching, and we could work on cleaning it up later?)
- Fwiw, the djangoproject.com source is under a BSD license, so I think we could certainly vendor parts of it into Django with appropriate license attribution. (There might be some concerns about the trademarked logos that the CSS places in the header, but we could maybe avoid those. Also, IANAL.)
2 Likes
Perhaps related, someone is working on dark mode for the issues site, and had questions about where shared resources should live - Where should shared CSS/JS assets for code.djangoproject.com live?
@kehach07 would you mind describing your intended approach? Maybe there is a common repo of foundational styles / css variables we can work towards?
Regarding the legalities, can we just cold call? Django Software Foundation
1 Like
I’ve opened draft PR Fixed #37138 -- Borrowed djangoproject.com theme for docs builds. by medmunds · Pull Request #21416 · django/django · GitHub. It mostly works, but needs some cleanup and is missing auxiliary pages like indexes and search results.
You can see the results in the RTD preview build for that PR.
The main difficulty turned out to be adapting (and reducing) the djangoproject.com templates for use directly with Sphinx. There will be a bit of effort to monitor future upstream template changes, but looking at the history very few changes would have affected the parts I copied anyway. (So it might be OK to just ignore upstream template updates until something breaks.)
For updating the CSS and other static assets, I added a docs Makefile recipe that automates fetching them from the djangoproject.com repo. This is run only on demand—not as part of ordinary docs builds—and the results are meant to be committed to the django repo.
Let me know what you think or if you spot any problems.
3 Likes
I’ve completed the missing parts of the PR to update Django’s docs theme and believe it’s ready for review. (And I found a few other bugs along the way, reported separately.)
Somewhat related, how would we feel about changing the ReadTheDocs config to use Sphinx’s “dirhtml” builder? That would make the URLs in PR preview builds closer to what you’d find on docs.djangoproject.com (no .html extensions).
1 Like
