#35335: Update "Enabling the sites framework" documentation to reiterate the ability to use `get_current_site` -------------------------------------+------------------------------------- Reporter: Sam Darwin | Owner: sam Type: | darwin Cleanup/optimization | Status: assigned Component: contrib.sites | Version: 5.0 Severity: Normal | Resolution: Keywords: | Triage Stage: Accepted Has patch: 1 | Needs documentation: 0 Needs tests: 0 | Patch needs improvement: 1 Easy pickings: 0 | UI/UX: 0 -------------------------------------+------------------------------------- Changes (by Natalia Bidart):
* component: Documentation => contrib.sites * has_patch: 0 => 1 * keywords: documentation => * needs_better_patch: 0 => 1 * owner: nobody => sam darwin * stage: Unreviewed => Accepted * status: new => assigned * summary: "sites" framework documentation => Update "Enabling the sites framework" documentation to reiterate the ability to use `get_current_site` Comment: Hello Sam, thank you for your ticket. Inline some thoughts about your proposal. Replying to [ticket:35335 Sam Darwin]: > 1. It says "To enable the sites framework, define a SITE_ID setting". The docs says, way before the reference above, the following: > ''The SITE_ID setting specifies the database ID of the Site object associated with that particular settings file. If the setting is omitted, the get_current_site() function will try to get the current site by comparing the domain with the host name from the request.get_host() method''. 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. > 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, [...] it would be even more clear to state "you must run multiple actual servers. One server isn't enough.". 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, a `server` refers simply to a hardware instance or compute node capable of running one or multiple websites. With Django's sites, each `Site` 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. > 3. Include a "recommendation" to the developer. [...] with that in mind, a proposed documentation update is covered in a new pull request https://github.com/django/django/pull/17977 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. -- Ticket URL: <https://code.djangoproject.com/ticket/35335#comment:1> 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 django-updates+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/django-updates/0107018e81c1eaeb-9f414de6-b778-40a7-a0cc-7e7e5060ddff-000000%40eu-central-1.amazonses.com.