Re: [Django] #35335: Update "Enabling the sites framework" documentation to reiterate the ability to use `get_current_site` (was: "sites" framework documentation)

[Django]

#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.