#35335: "sites" framework documentation
-------------------------------------+-------------------------------------
Reporter: sdarwin | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: | Version: 5.0
Documentation |
Severity: Normal | Keywords: documentation
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
Hi,
I was recently implementing the Django "sites" framework on a website, and
encountered issues with the documentation that could likely be improved.
1. It says "To enable the sites framework, define a SITE_ID setting".
I believe this is factually wrong. The latest and most modern way to use
the framework is with `get_current_site(request)`, and in that case a
SITE_ID will interfere. So, it should at least say "(optional)" there. Or
even go further, and discourage setting a SITE_ID.
2. Imagine someone is learning about the "sites" framework for the first
time. If there is something sort of surprising or unusual about a feature,
it would be helpful to comment on that, and not leave it "implied" or
unstated. In this case, what I think is unexpected is when you read these
instructions about SITE_ID, and you think "ok, so how does this all
work....", is the fact you would need to run multiple app servers,
multiple web servers. Not one server. Not a few horizontally scaled
replicas (which is often the scenario). Rather, multiple distinct app
servers, each with a separate SITE_ID. Yes, while this is "implied" by the
current documentation, it would be even more clear to state "you must run
multiple actual servers. One server isn't enough.".
At the same time, that's inconvenient, right? Which leads to the next
point:
3. Include a "recommendation" to the developer. There is a choice
between statically defining a SITE_ID in the config, or else dynamically
ascertaining the SITE_ID by using `get_current_site(request)`. Since
get_current_site is probably better, it wouldn't hurt to mention that.
However the words "recommend" or "recommendation" do not appear on the
page of documentation.
with that in mind, a proposed documentation update is covered in a new
pull request https://github.com/django/django/pull/17977 .
Thanks.
--
Ticket URL: <https://code.djangoproject.com/ticket/35335>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/0107018e8024405f-b0c072ae-7384-4dc9-814a-de26eb51a5b3-000000%40eu-central-1.amazonses.com.
