Opened 7 months ago
Last modified 7 months ago
#35335 assigned Cleanup/optimization
Update "Enabling the sites framework" documentation to reiterate the ability to use `get_current_site`
Reported by: | Sam Darwin | Owned by: | sam darwin |
---|---|---|---|
Component: | contrib.sites | Version: | 5.0 |
Severity: | Normal | Keywords: | |
Cc: | Sam Darwin | Triage Stage: | Accepted |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | yes |
Easy pickings: | no | UI/UX: | no |
Description
Hi,
I was recently implementing the Django "sites" framework on a website, and encountered issues with the documentation that could likely be improved.
- 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.
- 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:
- 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.
Change History (2)
comment:1 by , 7 months ago
Component: | Documentation → contrib.sites |
---|---|
Has patch: | set |
Keywords: | documentation removed |
Owner: | changed from | to
Patch needs improvement: | set |
Status: | new → assigned |
Summary: | "sites" framework documentation → Update "Enabling the sites framework" documentation to reiterate the ability to use `get_current_site` |
Triage Stage: | Unreviewed → Accepted |
comment:2 by , 7 months ago
too opinionated, and
contrasts with the intentional neutrality
In the world of software though, it's often possible that new libraries are introduced, new features are created, and then the general consensus is that you ought to tend towards the new method. Meanwhile, the earlier techniques can pass through phases where they are discouraged, deprecated, and finally obsolete and not supported at all.
Consider this quote, from a web search:
The os.system function is easy to use and interpret: simply use as input of the function the same command you would use in a shell. However, it is deprecated and it is recommended to use subprocess now.
Is it not true, that subprocess
is recommended, while os.system
is deprecated?
Or that Python 2 is completely unsupported, while the choice of Python 3 is strongly recommended (compared to Python 2) ?
It depends on the method in question. If get_current_site(request)
is newer and has more robust features than get_current()
, then it could be analogous to os.system
versus subprocess
. Certain options actually can become deprecated and/or recommended. And when that occurs, it isn't lacking in neutrality to discuss them.
Hello Sam, thank you for your ticket. Inline some thoughts about your proposal.
Replying to Sam Darwin:
The docs says, way before the reference above, the following:
I believe this explanation is quite accurate and explanatory. The sentence you mentioned appears halfway down the documentation, assuming that the reader has already read the preceding sections. Nevertheless, adding a clarification in the "Enabling the sites framework" section could help reinforce the previous point.
This is not entirely accurate. The term
server
can be interpreted differently by different people, leading to confusion rather than clarification. For instance, to me, aserver
refers simply to a hardware instance or compute node capable of running one or multiple websites. With Django's sites, eachSite
can have its own configuration, content, and templates. These sites can share the same (physical and virtual) server, or even the same Django project, depending on the requirements.I find this item to be a bit too much opinionated, which contrasts with the intentional neutrality of the Django docs. Moreover, the "Example usage" section demonstrates various clear but distinct patterns where using the sites framework could be advantageous, none of which mandates having different servers.
Considering these points, I believe the documentation could benefit from additional clarification in the "Enabling the sites framework" section. However, I don't advocate for further recommendations on how to use it unless they involve new examples that could be incorporated into the existing "Example usage" section. Accepting the ticket on this premise.