Update documentation to explain why `HttpRequest.build_absolute_uri` doesn't have a scheme option

[Rik]

Earlier I created #24459, where I wanted to add an option to HttpRequest.build_absolute_uri to be able to create a https URI on a http page, but we came to the conclusion this is the wrong solution to the problem, so I would like to add the explanation for this to the documentation.

I was thinking of a "Note" box with a text like:

"Django discourages mixing HTTP and HTTPS on the same domain. Therefore, build_absolute_uri will always generate an absolute URI with the same scheme the current request has."

[Sasha Romijn]

As we discussed, this seems like a good idea to me. I would change it to passive tense though, as the "Django recommends ..." looks a little odd to me. Site also seems more appropriate than domain to me. So I suggest: Mixing HTTP and HTTPS on the same site is discouraged.

[Bas Peschier]

I agree with Erik, otherwise the question "why does Django discourage it?" arises quickly. Referencing some documentation about why it is a bad idea might be a nice addition.

[Rik]

I couldn't find a good website where they explain the disadvantages clearly, and I think the explanation is maybe a bit too much to add in this part of the documentation. It could maybe be added somewhere else and linked to it, but I wouldn't know a good spot right of the top of my head now.

[Rik]

Created a pull request for this:

​https://github.com/django/django/pull/4278

[Erik Romijn <eromijn@…>]

In 794c3f74c32062d0f2ad021cb2af0e530b40730d:

Fixed #24460 -- Extended HttpRequest.build_absolute_uri documentation

Added explanation on why build_absolute_uri always enforces the
request's scheme.