Update "Enabling the sites framework" documentation to reiterate the ability to use `get_current_site`

[Sam Darwin]

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.

[Natalia Bidart]

Hello Sam, thank you for your ticket. Inline some thoughts about your proposal.

Replying to 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.

[Sam Darwin]

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.