Why does local django docs have a different styling/theme than the official one?

Django Internals Website
1

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

2

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 :sparkles:

1 Like