0
0
mirror of https://github.com/wagtail/wagtail.git synced 2024-11-24 01:57:32 +01:00

Replace hardcoded Django docs links to intersphinx links

This commit is contained in:
Sage Abdullah 2024-11-01 17:30:48 +00:00
parent 9d69863f3c
commit 857b26e5a0
No known key found for this signature in database
GPG Key ID: EB1A33CC51CC0217
25 changed files with 34 additions and 39 deletions

View File

@ -18,7 +18,7 @@ class User(AbstractUser):
```
Add the app containing your user model to `INSTALLED_APPS` - it must be above the `'wagtail.users'` line,
in order to override Wagtail's built-in templates - and set [AUTH_USER_MODEL](https://docs.djangoproject.com/en/stable/topics/auth/customizing/#substituting-a-custom-user-model) to reference
in order to override Wagtail's built-in templates - and set [`AUTH_USER_MODEL`](inv:django#auth-custom-user) to reference
your model. In this example the app is called `myapp` and the model is `User`.
```python

View File

@ -6,7 +6,7 @@ Wagtail follows [Djangos conventions for managing uploaded files](inv:django#
## File storage location
Wagtail uses the [`STORAGES["default"]`](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-STORAGES) setting to determine where and how user-uploaded files are stored. By default, Wagtail stores files in the local filesystem.
Wagtail uses the [`STORAGES["default"]`](inv:django#STORAGES) setting to determine where and how user-uploaded files are stored. By default, Wagtail stores files in the local filesystem.
## Serving documents
@ -43,7 +43,7 @@ WAGTAILDOCS_INLINE_CONTENT_TYPES = ['application/pdf', 'text/plain']
Wagtail allows you to specify the permitted file extensions for document uploads using the [WAGTAILDOCS_EXTENSIONS](wagtaildocs_extensions) setting.
It also validates the extensions using Django's [FileExtensionValidator](https://docs.djangoproject.com/en/stable/ref/validators/#fileextensionvalidator). For example:
It also validates the extensions using Django's {class}`~django.core.validators.FileExtensionValidator`. For example:
```python
WAGTAILDOCS_EXTENSIONS = ['pdf', 'docx']

View File

@ -241,7 +241,7 @@ To allow all of the page trees to be served at the same domain, we need
to add a URL prefix for each language.
To implement this, we can use Django's built-in
[i18n_patterns](https://docs.djangoproject.com/en/stable/topics/i18n/translation/#language-prefix-in-url-patterns)
{func}`~django.conf.urls.i18n.i18n_patterns`
function, which adds a language prefix to all of the URL patterns passed into it.
This activates the language code specified in the URL and Wagtail takes this into
account when it decides how to route the request.
@ -412,7 +412,7 @@ the name of the locale in its own language. We also add `rel` and `hreflang` att
`translation.locale` is an instance of the [Locale model](locale_model_ref).
Alternatively, a built-in tag from Django that gets info about the language of the translation.
For more information, see [get_language_info in the Django docs](https://docs.djangoproject.com/en/stable/topics/i18n/translation/#get-language-info).
For more information, see [`{% get_language_info %}` in the Django docs](inv:django:std:templatetag#get_language_info).
```html+django
{% load i18n %}
@ -427,7 +427,7 @@ languages and finds the page for each one. This works better than the [Basic exa
above on sites that have extra Django `LANGUAGES` that share the same Wagtail content.
For this example to work, you firstly need to add Django's
[django.template.context_processors.i18n](https://docs.djangoproject.com/en/stable/ref/templates/api/#django-template-context-processors-i18n)
[`django.template.context_processors.i18n`](django.template.context_processors.i18n)
context processor to your `TEMPLATES` setting:
```python
@ -699,7 +699,7 @@ If there is no language selected by the user, the `LANGUAGE_CODE` will be used.
The default language of Wagtail is `en-us` (American English). You can change this by tweaking a couple of Django settings:
- Make sure [USE_I18N](https://docs.djangoproject.com/en/stable/ref/settings/#use-i18n) is set to `True`
- Set [LANGUAGE_CODE](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-LANGUAGE_CODE) to your websites' primary language
- Make sure [`USE_I18N`](inv:django#USE_I18N) is set to `True`
- Set [`LANGUAGE_CODE`](inv:django#LANGUAGE_CODE) to your websites' primary language
If there is a translation available for your language, the Wagtail admin backend should now be in the language you've chosen.

View File

@ -89,4 +89,4 @@ The following methods can be overridden on your custom `Image` or `Rendition` mo
.. automethod:: get_upload_to
```
Refer to the Django [`FileField.upload_to`](https://docs.djangoproject.com/en/stable/ref/models/fields/#django.db.models.FileField.upload_to) function to further understand how the function works.
Refer to the Django [`FileField.upload_to`](django.db.models.FileField.upload_to) function to further understand how the function works.

View File

@ -84,7 +84,7 @@ import rustface.willow
registry.register_plugin(rustface.willow)
```
For example, in an app's [AppConfig.ready](https://docs.djangoproject.com/en/stable/ref/applications/#django.apps.AppConfig.ready).
For example, in an app's [`AppConfig.ready`](django.apps.AppConfig.ready).
## Cropping

View File

@ -288,7 +288,7 @@ class MyPageTest(WagtailPageTestCase):
### Using `dumpdata`
Creating [fixtures](inv:django#howto/initial-data) for tests is best done by creating content in a development
environment, and using Django's [dumpdata](https://docs.djangoproject.com/en/stable/ref/django-admin/#django-admin-dumpdata) command.
environment, and using Django's [`dumpdata`](inv:django#dumpdata) command.
Note that by default `dumpdata` will represent `content_type` by the primary key; this may cause consistency issues when adding / removing models, as content types are populated separately from fixtures. To prevent this, use the `--natural-foreign` switch, which represents content types by `["app", "model"]` instead.

View File

@ -145,7 +145,7 @@ DATABASE_ENGINE=django.db.backends.mysql python runtests.py
This will create a new database called `test_wagtail` in MySQL and run
the tests against it.
If you need to use different connection settings, use the following environment variables which correspond to the respective keys within Django's [DATABASES](https://docs.djangoproject.com/en/stable/ref/settings/#databases) settings dictionary:
If you need to use different connection settings, use the following environment variables which correspond to the respective keys within Django's [`DATABASES`](inv:django#DATABASES) settings dictionary:
- `DATABASE_ENGINE`
- `DATABASE_NAME`

View File

@ -350,7 +350,7 @@ Instead, review the issue, understand it and if you feel you can contribute you
## Helpful links
- [Django's contributor guide](https://docs.djangoproject.com/en/dev/internals/contributing/) is a helpful resource for contributors, even those not contributing to Wagtail.
- [Django's contributor guide](inv:django#internals/contributing/index) is a helpful resource for contributors, even those not contributing to Wagtail.
- [MDN's open source etiquette](https://developer.mozilla.org/en-US/docs/MDN/Community/Open_source_etiquette) is a great guideline for how to be a great contributor.
- [Learning Git Branching](https://learngitbranching.js.org/) a solid interactive guide to understand how git branching works.
- [Hacktoberfest](https://hacktoberfest.com/) every October, join in the fun and submit pull requests.

View File

@ -19,7 +19,7 @@ If you want to send an encrypted email (optional), the public key ID for <securi
This information can also be found in our [security.txt](https://wagtail.org/.well-known/security.txt).
Django security issues should be reported directly to the Django Project, following [Django's security policies](https://docs.djangoproject.com/en/dev/internals/security/) (upon which Wagtail's own policies are based).
Django security issues should be reported directly to the Django Project, following [Django's security policies](inv:django#internals/security) (upon which Wagtail's own policies are based).
## Supported versions

View File

@ -100,7 +100,7 @@ You can import `i18n` and then translate with the `translate`/`blocktranslate` t
```
**Note**: In Wagtail code, you might see `trans` and `blocktrans` instead of `translate` and `blocktranslate`.
This still works fine. `trans` and `blocktrans` were the tags earlier on in Django, but were replaced in [Django 3.1](https://docs.djangoproject.com/en/3.1/topics/i18n/translation/#translate-template-tag).
This still works fine. `trans` and `blocktrans` were the tags earlier on in Django, but [were replaced in Django 3.1](https://docs.djangoproject.com/en/5.1/releases/3.1/#templates).
## Additional resources

View File

@ -24,7 +24,7 @@ We use [djhtml](https://github.com/rtts/djhtml) for formatting and [Curlylint](h
- Follow [ARIA authoring practices](https://w3c.github.io/aria-practices/), in particular, [No ARIA is better than Bad ARIA](https://w3c.github.io/aria-practices/#no_aria_better_bad_aria).
- Use IDs for semantics only, classes for styling, `data-` attributes for JavaScript behavior.
- Order attributes with `id` first, then `class`, then any `data-` or other attributes with Stimulus `data-controller` first.
- For comments, use [Django template syntax](https://docs.djangoproject.com/en/stable/ref/templates/language/#comments) instead of HTML.
- For comments, use [Django template syntax](inv:django#template-comments) instead of HTML.
## CSS guidelines

View File

@ -29,7 +29,7 @@ We recommend enabling [ManifestStaticFilesStorage](django.contrib.staticfiles.st
Wagtail follows [Django's conventions for managing uploaded files](inv:django#topics/files).
So by default, Wagtail uses Django's built-in `FileSystemStorage` class which stores files on your site's server, in the directory specified by the `MEDIA_ROOT` setting.
Alternatively, Wagtail can be configured to store uploaded images and documents on a cloud storage service such as Amazon S3;
this is done through the [`STORAGES["default"]`](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-STORAGES)
this is done through the [`STORAGES["default"]`](inv:django#STORAGES)
setting in conjunction with an add-on package such as [django-storages](https://django-storages.readthedocs.io/).
#### Security

View File

@ -305,8 +305,3 @@ class MyAppConfig(AppConfig):
from .signal_handlers import register_signal_handlers
register_signal_handlers()
```
```{note}
In Django versions before 3.2 your `AppConfig` subclass needs to be set as `default_app_config` in `<project>/__init__.py`.
See the [relevant section in the Django docs](https://docs.djangoproject.com/en/3.1/ref/applications/#for-application-authors) for the version you are using.
```

View File

@ -23,7 +23,7 @@ Within Wagtail's admin interface, there are a few ways to add JavaScript.
The simplest way is to add global JavaScript files via hooks, see [](insert_editor_js) and [](insert_global_admin_js).
For JavaScript added when a specific Widget is used you can add an inner `Media` class to ensure that the file is loaded when the widget is used, see [Django's docs on their form `Media` class](https://docs.djangoproject.com/en/stable/topics/forms/media/#assets-as-a-static-definition).
For JavaScript added when a specific Widget is used you can add an inner `Media` class to ensure that the file is loaded when the widget is used, see [Django's docs on their form `Media` class](inv:django#assets-as-a-static-definition).
In a similar way, Wagtail's [](./template_components) provide a `media` property or `Media` class to add scripts when rendered.

View File

@ -121,7 +121,7 @@ urlpatterns = [
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
```
Note that this only works in development mode (`DEBUG = True`); in production, you have to configure your web server to serve files from `MEDIA_ROOT`. For further details, see the Django documentation: [Serving files uploaded by a user during development](https://docs.djangoproject.com/en/stable/howto/static-files/#serving-files-uploaded-by-a-user-during-development) and [Deploying static files](inv:django#howto/static-files/deployment).
Note that this only works in development mode (`DEBUG = True`); in production, you have to configure your web server to serve files from `MEDIA_ROOT`. For further details, see the Django documentation: [Serving files uploaded by a user during development](<inv:django#howto/static-files/index:serving files uploaded by a user during development>) and [Deploying static files](inv:django#howto/static-files/deployment).
With this configuration in place, you are ready to run `python manage.py migrate` to create the database tables used by Wagtail.

View File

@ -164,7 +164,7 @@ class HomePage(Page):
```
`body` is a `RichTextField`, a special Wagtail field. When `blank=True`,
it means the field isn't mandatory and you can leave it empty. You can use any of the [Django core fields](https://docs.djangoproject.com/en/stable/ref/models/fields). `content_panels` define the capabilities and the layout of the editing interface. Adding fields to `content_panels` enables you to edit them in the Wagtail [admin interface](https://guide.wagtail.org/en-latest/concepts/wagtail-interfaces/#admin-interface). You can read more about this on [Page models](../topics/pages).
it means the field isn't mandatory and you can leave it empty. You can use any of the [Django core fields](inv:django#ref/models/fields). `content_panels` define the capabilities and the layout of the editing interface. Adding fields to `content_panels` enables you to edit them in the Wagtail [admin interface](https://guide.wagtail.org/en-latest/concepts/wagtail-interfaces/#admin-interface). You can read more about this on [Page models](../topics/pages).
Run:
@ -199,7 +199,7 @@ to the model. Wagtail uses normal Django templates to render each page
type. By default, it looks for a template filename formed from the app and model name,
separating capital letters with underscores. For example, `HomePage` within the "home" app becomes
`home/home_page.html`. This template file can exist in any location that
[Django's template rules](https://docs.djangoproject.com/en/stable/intro/tutorial03/#write-views-that-actually-do-something) recognize. Conventionally, you can place it within a `templates` folder within the app.
[Django's template rules](<inv:django#intro/tutorial03:write views that actually do something>) recognize. Conventionally, you can place it within a `templates` folder within the app.
Edit `home/templates/home/home_page.html` to contain the following:

View File

@ -58,7 +58,7 @@ class FormPage(AbstractEmailForm):
`AbstractEmailForm` defines the fields `to_address`, `from_address` and `subject`, and expects `form_fields` to be defined. Any additional fields are treated as ordinary page content - note that `FormPage` is responsible for serving both the form page itself and the landing page after submission, so the model definition should include all necessary content fields for both of those views.
Date and datetime values in a form response will be formatted with the [SHORT_DATE_FORMAT](https://docs.djangoproject.com/en/stable/ref/settings/#short-date-format) and [SHORT_DATETIME_FORMAT](https://docs.djangoproject.com/en/stable/ref/settings/#short-datetime-format) respectively. (see [](form_builder_render_email) for how to customize the email content).
Date and datetime values in a form response will be formatted with the [`SHORT_DATE_FORMAT`](inv:django#SHORT_DATE_FORMAT) and [`SHORT_DATETIME_FORMAT`](inv:django#SHORT_DATETIME_FORMAT) respectively. (see [](form_builder_render_email) for how to customize the email content).
If you do not want your form page type to offer form-to-email functionality, you can inherit from AbstractForm instead of `AbstractEmailForm`, and omit the `to_address`, `from_address`, and `subject` fields from the `content_panels` definition.

View File

@ -296,7 +296,7 @@ Or, alternately, using the `set` tag:
For models with foreign key relationships to other objects (for example pages),
which are very often needed to output values in templates, you can set
the `select_related` attribute on your model to have Wagtail utilize
Django's [QuerySet.select_related()](https://docs.djangoproject.com/en/stable/ref/models/querysets/#select-related)
Django's [`QuerySet.select_related()`](django.db.models.query.QuerySet.select_related)
method to fetch the settings object and related objects in a single query.
With this, the initial query is more complex, but you will be able to
freely access the foreign key values without any additional queries,

View File

@ -217,7 +217,7 @@ WAGTAIL_DATETIME_FORMAT = '%d.%m.%Y. %H:%M'
WAGTAIL_TIME_FORMAT = '%H:%M'
```
Specifies the date, time, and datetime format to be used in input fields in the Wagtail admin. The format is specified in [Python datetime module syntax](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior) and must be one of the recognized formats listed in the `DATE_INPUT_FORMATS`, `TIME_INPUT_FORMATS`, or `DATETIME_INPUT_FORMATS` setting respectively (see [DATE_INPUT_FORMATS](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DATE_INPUT_FORMATS)).
Specifies the date, time, and datetime format to be used in input fields in the Wagtail admin. The format is specified in [Python datetime module syntax](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior) and must be one of the recognized formats listed in the [`DATE_INPUT_FORMATS`](inv:django#DATE_INPUT_FORMATS), [`TIME_INPUT_FORMATS`](inv:django#TIME_INPUT_FORMATS), or [`DATETIME_INPUT_FORMATS`](inv:django#DATETIME_INPUT_FORMATS) setting respectively.
For example, to use US Imperial style date and time format (AM/PM times) in the Wagtail Admin, you'll need to override the Django format for your site's locale.
@ -420,7 +420,7 @@ WAGTAILIMAGES_RENDITION_STORAGE = 'myapp.backends.MyCustomStorage'
WAGTAILIMAGES_RENDITION_STORAGE = MyCustomStorage()
```
This setting allows image renditions to be stored using an alternative storage configuration. It is recommended to use a storage alias defined in [Django's STORAGES setting](https://docs.djangoproject.com/en/stable/ref/settings/#std-setting-STORAGES). Alternatively, this setting also accepts a dotted module path to a `Storage` subclass, or an instance of such a subclass. The default is `None`, meaning renditions will use the project's default storage.
This setting allows image renditions to be stored using an alternative storage configuration. It is recommended to use a storage alias defined in [Django's `STORAGES` setting](inv:django#STORAGES). Alternatively, this setting also accepts a dotted module path to a `Storage` subclass, or an instance of such a subclass. The default is `None`, meaning renditions will use the project's default storage.
Custom storage classes should subclass `django.core.files.storage.Storage`. See the {doc}`Django file storage API <django:ref/files/storage>` for more information.

View File

@ -116,7 +116,7 @@ This release upgrades the [django-taggit](https://django-taggit.readthedocs.io/e
### `wagtail.admin.views.generic.DeleteView` follows Django 4.0 conventions
The internal (undocumented) class-based view `wagtail.admin.views.generic.DeleteView` has been updated to align with [Django 4.0's `DeleteView` implementation](https://docs.djangoproject.com/en/4.0/releases/4.0/#deleteview-changes), which uses `FormMixin` to handle POST requests. Any custom deletion logic in `delete()` handlers should be moved to `form_valid()`.
The internal (undocumented) class-based view `wagtail.admin.views.generic.DeleteView` has been updated to align with [Django 4.0's `DeleteView` implementation](https://docs.djangoproject.com/en/stable/releases/4.0/#deleteview-changes), which uses `FormMixin` to handle POST requests. Any custom deletion logic in `delete()` handlers should be moved to `form_valid()`.
### Renamed admin/expanding-formset.js

View File

@ -164,8 +164,8 @@ All uses of `StreamField` should be updated to include the argument `use_json_fi
### SQLite now requires the `JSON1` extension enabled
Due to [`JSONField`](https://docs.djangoproject.com/en/stable/ref/models/fields/#django.db.models.JSONField) requirements, SQLite will only be supported with the JSON1 extension enabled.
See [Enabling JSON1 extension on SQLite](https://docs.djangoproject.com/en/stable/ref/databases/#sqlite-json1) and [JSON1 extension](https://www.sqlite.org/json1.html) for details.
Due to {class}`~django.db.models.JSONField` requirements, SQLite will only be supported with the JSON1 extension enabled.
See [Enabling JSON1 extension on SQLite](inv:django#sqlite-json1) and [JSON1 extension](https://www.sqlite.org/json1.html) for details.
## Upgrade considerations - deprecation of old functionality

View File

@ -425,8 +425,8 @@ As part of the page editor redesign, we have removed support for the `classname=
### Optional replacement for regex only `route` decorator for `RoutablePageMixin`
- This is an optional replacement, there are no immediate plans to remove the `route` decorator at this time.
- The `RoutablePageMixin` contrib module now provides a `path` decorator that behaves the same way as Django's [`django.urls.path`](https://docs.djangoproject.com/en/stable/ref/urls/#django.urls.path) function.
- `RoutablePageMixin`'s `route` decorator will now redirect to a new `re_path` decorator that emulates the behavior of [`django.urls.re_path`](https://docs.djangoproject.com/en/stable/ref/urls/#django.urls.re_path).
- The `RoutablePageMixin` contrib module now provides a `path` decorator that behaves the same way as Django's {func}`django.urls.path` function.
- `RoutablePageMixin`'s `route` decorator will now redirect to a new `re_path` decorator that emulates the behavior of {func}`django.urls.re_path`.
### `BaseSetting` model replaced by `BaseSiteSetting`

View File

@ -47,7 +47,7 @@ To upgrade:
- Make any necessary code changes as directed in the "Upgrade considerations" section of the release notes.
- Test that your project is working as expected.
Remember that the JavaScript and CSS files used in the Wagtail admin may have changed between releases - if you encounter erratic behavior on upgrading, ensure that you have cleared your browser cache. When deploying the upgrade to a production server, be sure to run `./manage.py collectstatic` to make the updated static files available to the web server. In production, we recommend enabling [ManifestStaticFilesStorage](https://docs.djangoproject.com/en/stable/ref/contrib/staticfiles/#manifeststaticfilesstorage) in the `STORAGES["staticfiles"]` setting - this ensures that different versions of files are assigned distinct URLs.
Remember that the JavaScript and CSS files used in the Wagtail admin may have changed between releases - if you encounter erratic behavior on upgrading, ensure that you have cleared your browser cache. When deploying the upgrade to a production server, be sure to run `./manage.py collectstatic` to make the updated static files available to the web server. In production, we recommend enabling {class}`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` in the [`STORAGES["staticfiles"]` setting](inv:django#STORAGES) - this ensures that different versions of files are assigned distinct URLs.
(compatible_django_python_versions)=

View File

@ -2,7 +2,7 @@
# Permissions
Wagtail adapts and extends [the Django permission system](https://docs.djangoproject.com/en/stable/topics/auth/default/#topic-authorization) to cater to the needs of website content creation, such as moderation workflows, and multiple teams working on different areas of a site (or multiple sites within the same Wagtail installation). Permissions can be configured through the 'Groups' area of the Wagtail admin interface, under 'Settings'.
Wagtail adapts and extends [the Django permission system](inv:django#topic-authorization) to cater to the needs of website content creation, such as moderation workflows, and multiple teams working on different areas of a site (or multiple sites within the same Wagtail installation). Permissions can be configured through the 'Groups' area of the Wagtail admin interface, under 'Settings'.
```{note}
Whilst Wagtail supports a number of user roles and permissions, the Wagtail Admin should still be restricted to trusted users.
@ -61,7 +61,7 @@ Users are not allowed to move or delete the collection that is used to assign th
## Adding custom permissions
See Django's documentation on [custom permissions](https://docs.djangoproject.com/en/stable/topics/auth/customizing/#custom-permissions) for details on how to set permissions up.
See Django's documentation on [custom permissions](inv:django#custom-permissions) for details on how to set permissions up.
Permissions for models registered with Wagtail will automatically show up in the Wagtail admin Group edit form. For other models, you can also add the permissions using the `register_permissions` hook (see [](register_permissions)).

View File

@ -331,7 +331,7 @@ if the page supports [multiple preview modes](wagtail.models.Page.preview_modes)
## Template fragment caching
Django supports [template fragment caching](https://docs.djangoproject.com/en/stable/topics/cache/#template-fragment-caching), which allows caching portions of a template. Using Django's `{% cache %}` tag natively with Wagtail can be [dangerous](https://github.com/wagtail/wagtail/issues/5074) as it can result in preview content being shown to end users. Instead, Wagtail provides 2 extra template tags which can be loaded from `wagtail_cache`:
Django supports [template fragment caching](<inv:django:std:label#topics/cache:template fragment caching>), which allows caching portions of a template. Using Django's `{% cache %}` tag natively with Wagtail can be [dangerous](https://github.com/wagtail/wagtail/issues/5074) as it can result in preview content being shown to end users. Instead, Wagtail provides 2 extra template tags which can be loaded from `wagtail_cache`:
(wagtailcache)=