Fixes #12561
When a ModelForm is constructed without passing an `initial` instance, the result of `StreamField.get_default()` will become the default value of the form field without the intermediate step of being set on a model instance and read back (which would have the side effect of calling `normalize()`). Form rendering only works with normalized values (e.g. StreamValue rather than list-of-tuples for a StreamBlock), so the return value from `get_default()` needs to be normalized.
As made famous by https://youtu.be/v3KEaMTfKg0?t=319 :-)
By design, Wagtail tolerates the default Site record being left at its default value of 'localhost' up to a certain point. Ideally, that point should be when it becomes strictly necessary for Wagtail to care about hostnames (such as when setting up the second site of a multi-site installation) and it should be clear to the developer what has happened and how to fix it.
In practice, that point often comes when the developer deploys their site to production, sets `DEBUG=False`, and is then required by Django to set `ALLOWED_HOSTS` to their real domain name. At this point, front-end page requests work (because the initial site record is default=True, matching any domain including the live one) but previews are broken (because the dummy request object is still formed using localhost as per the site's hostname field, which is disallowed by ALLOWED_HOSTS).
This is unnecessary, and can be avoided by validating the hostname against ALLOWED_HOSTS and substituting one that _is_ allowed if necessary, as we already do for pages that don't have an associated site record.
Return `cleaned_data` for more consistent subclassing.
Updated documentation with an example of adding custom page validation for form fields.
Add unit test to ensure that the documented usage of extending `WagtailAdminFormPageForm` works as expected.
Originally from #10375
This is necessary for rST docs, i.e. in docstrings and in eval-rst
blocks. Without this, Sphinx cannot seem to understand the role. See:
https://stackoverflow.com/questions/13387125
MyST-Parser seems to be smarter, it can figure out these custom
roles without having to register the types ourselves. This is evident in
the previous commits where I already use the :setting: role in markdown
docs.
Some link labels are changed to just the code part, because using Sphinx
roles for code objects (e.g. methods, attributes) would always format the
text as inline code.
It's currently impossible to customize the formatting of a link's text in
rST. See https://stackoverflow.com/questions/4743845
Add more emphasis on the divide between when to use Markdown and when to
use rST.
Also improve examples for versionadded and versionchanged directives.
