diff --git a/docs/advanced_topics/customisation/extending_draftail.rst b/docs/advanced_topics/customisation/extending_draftail.rst index 28f9b4520c..f06578a2c8 100644 --- a/docs/advanced_topics/customisation/extending_draftail.rst +++ b/docs/advanced_topics/customisation/extending_draftail.rst @@ -196,7 +196,7 @@ In order to achieve this, we start with registering the rich text feature like f The ``js`` and ``css`` keyword arguments on ``EntityFeature`` can be used to specify additional JS and CSS files to load when this feature is active. Both are optional. Their values are added to a ``Media`` object, more documentation on these objects -is available in the `Django Form Assets documentation `_. +is available in the :doc:`Django Form Assets documentation `. Since entities hold data, the conversion to/from database format is more complicated. We have to create the two handlers: diff --git a/docs/advanced_topics/customisation/extending_hallo.rst b/docs/advanced_topics/customisation/extending_hallo.rst index 81c45f82d7..4790817728 100644 --- a/docs/advanced_topics/customisation/extending_hallo.rst +++ b/docs/advanced_topics/customisation/extending_hallo.rst @@ -41,8 +41,8 @@ The constructor for ``HalloPlugin`` accepts the following keyword arguments: * ``name`` - the plugin name as defined in the JavaScript code. ``hallo.js`` plugin names are prefixed with the ``"IKS."`` namespace, but the name passed here should be without the prefix. * ``options`` - a dictionary (or other JSON-serialisable object) of options to be passed to the JavaScript plugin code on initialisation - * ``js`` - a list of JavaScript files to be imported for this plugin, defined in the same way as a `Django form media `_ definition - * ``css`` - a dictionary of CSS files to be imported for this plugin, defined in the same way as a `Django form media `_ definition + * ``js`` - a list of JavaScript files to be imported for this plugin, defined in the same way as a :doc:`Django form media ` definition + * ``css`` - a dictionary of CSS files to be imported for this plugin, defined in the same way as a :doc:`Django form media ` definition * ``order`` - an index number (default 100) specifying the order in which plugins should be listed, which in turn determines the order buttons will appear in the toolbar When writing the front-end code for the plugin, Wagtail’s Hallo implementation offers two extension points: diff --git a/docs/advanced_topics/deploying.rst b/docs/advanced_topics/deploying.rst index ce7bd7a379..05c4978ff3 100644 --- a/docs/advanced_topics/deploying.rst +++ b/docs/advanced_topics/deploying.rst @@ -6,7 +6,7 @@ On your server Wagtail is straightforward to deploy on modern Linux-based distributions, but see the section on :doc:`performance ` for the non-Python services we recommend. -Our current preferences are for Nginx, Gunicorn and supervisor on Debian, but Wagtail should run with any of the combinations detailed in Django's `deployment documentation `_. +Our current preferences are for Nginx, Gunicorn and supervisor on Debian, but Wagtail should run with any of the combinations detailed in Django's :doc:`deployment documentation `. On Divio Cloud ~~~~~~~~~~~~~~ @@ -34,15 +34,15 @@ Deployment tips Static files ++++++++++++ -As with all Django projects, static files are not served by the Django application server in production (i.e. outside of the ``manage.py runserver`` command); these need to be handled separately at the web server level. See `Django's documentation on deploying static files `_. +As with all Django projects, static files are not served by the Django application server in production (i.e. outside of the ``manage.py runserver`` command); these need to be handled separately at the web server level. See :doc:`Django's documentation on deploying static files `. -The JavaScript and CSS files used by the Wagtail admin frequently change between releases of Wagtail - it's important to avoid serving outdated versions of these files due to browser or server-side caching, as this can cause hard-to-diagnose issues. We recommend enabling `ManifestStaticFilesStorage `_ in the ``STATICFILES_STORAGE`` setting - this ensures that different versions of files are assigned distinct URLs. +The JavaScript and CSS files used by the Wagtail admin frequently change between releases of Wagtail - it's important to avoid serving outdated versions of these files due to browser or server-side caching, as this can cause hard-to-diagnose issues. We recommend enabling :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` in the ``STATICFILES_STORAGE`` setting - this ensures that different versions of files are assigned distinct URLs. Cloud storage +++++++++++++ -Wagtail follows `Django's conventions for managing uploaded files `_, and can be configured to store uploaded images and documents on a cloud storage service such as Amazon S3; this is done through the `DEFAULT_FILE_STORAGE `_ setting in conjunction with an add-on package such as `django-storages `_. Be aware that setting up remote storage will not entirely offload file handling tasks from the application server - some Wagtail functionality requires files to be read back by the application server. In particular, documents are served through a Django view in order to enforce permission checks, and original image files need to be read back whenever a new resized rendition is created. +Wagtail follows :doc:`Django's conventions for managing uploaded files `, and can be configured to store uploaded images and documents on a cloud storage service such as Amazon S3; this is done through the `DEFAULT_FILE_STORAGE `_ setting in conjunction with an add-on package such as `django-storages `_. Be aware that setting up remote storage will not entirely offload file handling tasks from the application server - some Wagtail functionality requires files to be read back by the application server. In particular, documents are served through a Django view in order to enforce permission checks, and original image files need to be read back whenever a new resized rendition is created. Note that the django-storages Amazon S3 backends (``storages.backends.s3boto.S3BotoStorage`` and ``storages.backends.s3boto3.S3Boto3Storage``) **do not correctly handle duplicate filenames** in their default configuration. When using these backends, ``AWS_S3_FILE_OVERWRITE`` must be set to ``False``. diff --git a/docs/advanced_topics/documents/custom_document_model.rst b/docs/advanced_topics/documents/custom_document_model.rst index cdcac8e934..b512ba2590 100644 --- a/docs/advanced_topics/documents/custom_document_model.rst +++ b/docs/advanced_topics/documents/custom_document_model.rst @@ -54,7 +54,7 @@ Then in your settings module: When changing an existing site to use a custom document model, no documents will be copied to the new model automatically. Copying old documents to the new model would need to be done manually with a - `data migration `_. + :ref:`data migration `. Any templates that reference the builtin document model will still continue to work as before. diff --git a/docs/advanced_topics/i18n/index.rst b/docs/advanced_topics/i18n/index.rst index 2b2ec0a5b1..8dd0c164d1 100644 --- a/docs/advanced_topics/i18n/index.rst +++ b/docs/advanced_topics/i18n/index.rst @@ -4,7 +4,7 @@ Internationalisation This document describes the internationalisation features of Wagtail and how to create multi-lingual sites. -Wagtail uses Django's `Internationalisation framework `_ so most of the steps are the same as other Django projects. +Wagtail uses Django's :doc:`Internationalisation framework ` so most of the steps are the same as other Django projects. .. contents:: @@ -43,7 +43,7 @@ If there is a translation available for your language, the Wagtail admin backend Creating sites with multiple languages ====================================== -You can create sites with multiple language support by leveraging Django's `translation features `_. +You can create sites with multiple language support by leveraging Django's :doc:`translation features `. This section of the documentation will show you how to use Django's translation features with Wagtail and also describe a couple of methods for storing/retrieving translated content using Wagtail pages. @@ -63,7 +63,7 @@ To enable multi-language support, add ``django.middleware.locale.LocaleMiddlewar 'django.middleware.locale.LocaleMiddleware', ) -This middleware class looks at the user's browser language and sets the `language of the site accordingly `_. +This middleware class looks at the user's browser language and sets the :ref:`language of the site accordingly `. Serving different languages from different URLs diff --git a/docs/advanced_topics/images/custom_image_model.rst b/docs/advanced_topics/images/custom_image_model.rst index bd4e9d9c94..7ee5992fda 100644 --- a/docs/advanced_topics/images/custom_image_model.rst +++ b/docs/advanced_topics/images/custom_image_model.rst @@ -66,7 +66,7 @@ Then set the ``WAGTAILIMAGES_IMAGE_MODEL`` setting to point to it: When changing an existing site to use a custom image model, no images will be copied to the new model automatically. Copying old images to the new model would need to be done manually with a - `data migration `_. + :ref:`data migration `. Any templates that reference the builtin image model will still continue to work as before but would need to be updated in order to see any new images. diff --git a/docs/advanced_topics/jinja2.rst b/docs/advanced_topics/jinja2.rst index cda445ed49..8f7aa16f59 100644 --- a/docs/advanced_topics/jinja2.rst +++ b/docs/advanced_topics/jinja2.rst @@ -30,7 +30,7 @@ Django needs to be configured to support Jinja2 templates. As the Wagtail admin Jinja templates must be placed in a ``jinja2/`` directory in your app. The template for an ``EventPage`` model in an ``events`` app should be created at ``events/jinja2/events/event_page.html``. -By default, the Jinja environment does not have any Django functions or filters. The Django documentation has more information on `configuring Jinja for Django `_. +By default, the Jinja environment does not have any Django functions or filters. The Django documentation has more information on :class:`configuring Jinja for Django `. ``self`` in templates ===================== diff --git a/docs/advanced_topics/performance.rst b/docs/advanced_topics/performance.rst index df57ac2517..b8296fe956 100644 --- a/docs/advanced_topics/performance.rst +++ b/docs/advanced_topics/performance.rst @@ -45,7 +45,7 @@ Wagtail is tested on PostgreSQL, SQLite and MySQL. It should work on some third- Templates --------- -The overhead from reading and compiling templates can add up. In some cases a significant performance improvement can be gained by using `Django's cached template loader `_: +The overhead from reading and compiling templates can add up. In some cases a significant performance improvement can be gained by using :class:`Django's cached template loader `: .. code-block:: python diff --git a/docs/advanced_topics/settings.rst b/docs/advanced_topics/settings.rst index bfeb1c88ae..93da580fde 100644 --- a/docs/advanced_topics/settings.rst +++ b/docs/advanced_topics/settings.rst @@ -2,7 +2,7 @@ Configuring Django for Wagtail ============================== -To install Wagtail completely from scratch, create a new Django project and an app within that project. For instructions on these tasks, see `Writing your first Django app `_. Your project directory will look like the following:: +To install Wagtail completely from scratch, create a new Django project and an app within that project. For instructions on these tasks, see :doc:`Writing your first Django app `. Your project directory will look like the following:: myproject/ myproject/ @@ -18,7 +18,7 @@ To install Wagtail completely from scratch, create a new Django project and an a views.py manage.py -From your app directory, you can safely remove ``admin.py`` and ``views.py``, since Wagtail will provide this functionality for your models. Configuring Django to load Wagtail involves adding modules and variables to ``settings.py`` and URL configuration to ``urls.py``. For a more complete view of what's defined in these files, see `Django Settings `__ and `Django URL Dispatcher `_. +From your app directory, you can safely remove ``admin.py`` and ``views.py``, since Wagtail will provide this functionality for your models. Configuring Django to load Wagtail involves adding modules and variables to ``settings.py`` and URL configuration to ``urls.py``. For a more complete view of what's defined in these files, see :doc:`Django Settings ` and :doc:`Django URL Dispatcher `. What follows is a settings reference which skips many boilerplate Django settings. If you just want to get your Wagtail install up quickly without fussing with settings at the moment, see :ref:`complete_example_config`. @@ -136,7 +136,7 @@ Third-Party Apps Settings Variables (``settings.py``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Wagtail makes use of the following settings, in addition to `Django's core settings `__: +Wagtail makes use of the following settings, in addition to :doc:`Django's core settings `: Site Name @@ -161,7 +161,7 @@ Append Slash Similar to Django's ``APPEND_SLASH``, this setting controls how Wagtail will handle requests that don't end in a trailing slash. -When ``WAGTAIL_APPEND_SLASH`` is ``True`` (default), requests to Wagtail pages which omit a trailing slash will be redirected by Django's `CommonMiddleware`_ to a URL with a trailing slash. +When ``WAGTAIL_APPEND_SLASH`` is ``True`` (default), requests to Wagtail pages which omit a trailing slash will be redirected by Django's :class:`~django.middleware.common.CommonMiddleware` to a URL with a trailing slash. When ``WAGTAIL_APPEND_SLASH`` is ``False``, requests to Wagtail pages will be served both with and without trailing slashes. Page links generated by Wagtail, however, will not include trailing slashes. @@ -169,7 +169,6 @@ When ``WAGTAIL_APPEND_SLASH`` is ``False``, requests to Wagtail pages will be se If you use the ``False`` setting, keep in mind that serving your pages both with and without slashes may affect search engines' ability to index your site. See `this Google Webmaster Blog post`_ for more details. -.. _commonmiddleware: https://docs.djangoproject.com/en/dev/ref/middleware/#module-django.middleware.common .. _this Google Webmaster Blog post: https://webmasters.googleblog.com/2010/04/to-slash-or-not-to-slash.html Search diff --git a/docs/advanced_topics/testing.rst b/docs/advanced_topics/testing.rst index e9984c3d3a..2af5c59585 100644 --- a/docs/advanced_topics/testing.rst +++ b/docs/advanced_topics/testing.rst @@ -112,8 +112,8 @@ Fixtures Using ``dumpdata`` ------------------ -Creating fixtures_ for tests is best done by creating content in a development environment, -and using Django's dumpdata_ command. +Creating :doc:`fixtures ` for tests is best done by creating content in a development +environment, and using Django's 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. @@ -162,6 +162,5 @@ Filling in the ``path`` / ``numchild`` / ``depth`` fields is necessary in order The `Treebeard docs`_ might help in understanding how this works. -.. _fixtures: https://docs.djangoproject.com/en/2.0/howto/initial-data/ .. _dumpdata: https://docs.djangoproject.com/en/2.0/ref/django-admin/#django-admin-dumpdata .. _Treebeard docs: http://django-treebeard.readthedocs.io/en/latest/mp_tree.html diff --git a/docs/getting_started/tutorial.rst b/docs/getting_started/tutorial.rst index 1837d89a22..af210431b7 100644 --- a/docs/getting_started/tutorial.rst +++ b/docs/getting_started/tutorial.rst @@ -87,7 +87,7 @@ Edit ``home/models.py`` as follows, to add a ``body`` field to the model: ] ``body`` is defined as ``RichTextField``, a special Wagtail field. You -can use any of the `Django core fields `__. ``content_panels`` define the +can use any of the :doc:`Django core fields `. ``content_panels`` define the capabilities and the layout of the editing interface. :doc:`More on creating Page models. <../topics/pages>` Run ``python manage.py makemigrations``, then diff --git a/docs/reference/contrib/forms/customisation.rst b/docs/reference/contrib/forms/customisation.rst index f2f14d0644..9997f81e24 100644 --- a/docs/reference/contrib/forms/customisation.rst +++ b/docs/reference/contrib/forms/customisation.rst @@ -609,7 +609,7 @@ Customise form submissions listing in Wagtail Admin The Admin listing of form submissions can be customised by setting the attribute ``submissions_list_view_class`` on your FormPage model. -The list view class must be a subclass of ``SubmissionsListView`` from ``wagtail.contrib.forms.views``, which is a child class of `Django's class based ListView `_. +The list view class must be a subclass of ``SubmissionsListView`` from ``wagtail.contrib.forms.views``, which is a child class of Django's class based :class:`~django.views.generic.list.ListView`. Example: diff --git a/docs/reference/contrib/forms/index.rst b/docs/reference/contrib/forms/index.rst index 4bd2d57d2d..5672c99f8e 100644 --- a/docs/reference/contrib/forms/index.rst +++ b/docs/reference/contrib/forms/index.rst @@ -7,7 +7,7 @@ Form builder The ``wagtailforms`` module allows you to set up single-page forms, such as a 'Contact us' form, as pages of a Wagtail site. It provides a set of base models that site implementers can extend to create their own ``FormPage`` type with their own site-specific templates. Once a page type has been set up in this way, editors can build forms within the usual page editor, consisting of any number of fields. Form submissions are stored for later retrieval through a new 'Forms' section within the Wagtail admin interface; in addition, they can be optionally e-mailed to an address specified by the editor. .. note:: - **wagtailforms is not a replacement for** `Django's form support `_. It is designed as a way for page authors to build general-purpose data collection forms without having to write code. If you intend to build a form that assigns specific behaviour to individual fields (such as creating user accounts), or needs a custom HTML layout, you will almost certainly be better served by a standard Django form, where the fields are fixed in code rather than defined on-the-fly by a page author. See the `wagtail-form-example project `_ for an example of integrating a Django form into a Wagtail page. + **wagtailforms is not a replacement for** :doc:`Django's form support `. It is designed as a way for page authors to build general-purpose data collection forms without having to write code. If you intend to build a form that assigns specific behaviour to individual fields (such as creating user accounts), or needs a custom HTML layout, you will almost certainly be better served by a standard Django form, where the fields are fixed in code rather than defined on-the-fly by a page author. See the `wagtail-form-example project `_ for an example of integrating a Django form into a Wagtail page. .. _form_builder_usage: diff --git a/docs/reference/contrib/settings.rst b/docs/reference/contrib/settings.rst index 3b4e0621ad..8737fa89c7 100644 --- a/docs/reference/contrib/settings.rst +++ b/docs/reference/contrib/settings.rst @@ -85,7 +85,7 @@ with a custom ``edit_handler`` attribute: Appearance ---------- -You can change the label used in the menu by changing the `verbose_name `_ of your model. +You can change the label used in the menu by changing the :attr:`~django.db.models.Options.verbose_name` of your model. You can add an icon to the menu by passing an 'icon' argument to the ``register_setting`` decorator: diff --git a/docs/reference/hooks.rst b/docs/reference/hooks.rst index c0c6e8e9ec..92491948bd 100644 --- a/docs/reference/hooks.rst +++ b/docs/reference/hooks.rst @@ -175,9 +175,7 @@ Hooks for building new areas of the admin interface (alongside pages, images, do ``register_admin_urls`` ~~~~~~~~~~~~~~~~~~~~~~~ - Register additional admin page URLs. The callable fed into this hook should return a list of Django URL patterns which define the structure of the pages and endpoints of your extension to the Wagtail admin. For more about vanilla Django URLconfs and views, see `url dispatcher`_. - - .. _url dispatcher: https://docs.djangoproject.com/en/dev/topics/http/urls/ + Register additional admin page URLs. The callable fed into this hook should return a list of Django URL patterns which define the structure of the pages and endpoints of your extension to the Wagtail admin. For more about vanilla Django URLconfs and views, see :doc:`url dispatcher `. .. code-block:: python diff --git a/docs/reference/pages/model_reference.rst b/docs/reference/pages/model_reference.rst index 9b29fa1822..29d4906f3c 100644 --- a/docs/reference/pages/model_reference.rst +++ b/docs/reference/pages/model_reference.rst @@ -197,7 +197,7 @@ In addition to the model fields provided, ``Page`` has many properties and metho .. attribute:: is_creatable - Controls if this page can be created through the Wagtail administration. Defaults to True, and is not inherited by subclasses. This is useful when using `multi-table inheritance `_, to stop the base model from being created as an actual page. + Controls if this page can be created through the Wagtail administration. Defaults to ``True``, and is not inherited by subclasses. This is useful when using :ref:`multi-table inheritance `, to stop the base model from being created as an actual page. .. attribute:: max_count diff --git a/docs/reference/pages/panels.rst b/docs/reference/pages/panels.rst index 453d507849..8acd4d2ca5 100644 --- a/docs/reference/pages/panels.rst +++ b/docs/reference/pages/panels.rst @@ -26,9 +26,7 @@ FieldPanel .. attribute:: FieldPanel.widget (optional) - This parameter allows you to specify a `Django form widget`_ to use instead of the default widget for this field type. - -.. _django form widget: https://docs.djangoproject.com/en/dev/ref/forms/widgets/ + This parameter allows you to specify a :doc:`Django form widget ` to use instead of the default widget for this field type. MultiFieldPanel --------------- @@ -175,9 +173,7 @@ ImageChooserPanel ImageChooserPanel('cover'), ] - Django's default behaviour is to "cascade" deletions through a ForeignKey relationship, which may not be what you want. This is why the ``null``, ``blank``, and ``on_delete`` parameters should be set to allow for an empty field. (See `Django model field reference (on_delete)`_ ). ``ImageChooserPanel`` takes only one argument: the name of the field. - - .. _Django model field reference (on_delete): https://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.ForeignKey.on_delete + Django's default behaviour is to "cascade" deletions through a ForeignKey relationship, which may not be what you want. This is why the :attr:`~django.db.models.Field.null`, :attr:`~django.db.models.Field.blank`, and :attr:`~django.db.models.ForeignKey.on_delete` parameters should be set to allow for an empty field. ``ImageChooserPanel`` takes only one argument: the name of the field. Displaying ``Image`` objects in a template requires the use of a template tag. See :ref:`image_tag`. @@ -271,10 +267,7 @@ Here are some Wagtail-specific types that you might include as fields in your mo Field Customisation ~~~~~~~~~~~~~~~~~~~ -By adding CSS classes to your panel definitions or adding extra parameters to your field definitions, you can control much of how your fields will display in the Wagtail page editing interface. Wagtail's page editing interface takes much of its behaviour from Django's admin, so you may find many options for customisation covered there. (See `Django model field reference`_ ). - -.. _Django model field reference: https://docs.djangoproject.com/en/dev/ref/models/fields/ - +By adding CSS classes to your panel definitions or adding extra parameters to your field definitions, you can control much of how your fields will display in the Wagtail page editing interface. Wagtail's page editing interface takes much of its behaviour from Django's admin, so you may find many options for customisation covered there. (See :doc:`Django model field reference `). Full-Width Input ---------------- @@ -291,18 +284,12 @@ Use ``classname="title"`` to make Page's built-in title field stand out with mor Required Fields --------------- -To make input or chooser selection mandatory for a field, add ``blank=False`` to its model definition. (See `Django model field reference (blank)`_ ). - -.. _Django model field reference (blank): https://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.Field.blank - +To make input or chooser selection mandatory for a field, add :attr:`blank=False ` to its model definition. Hiding Fields ------------- -Without a panel definition, a default form field (without label) will be used to represent your fields. If you intend to hide a field on the Wagtail page editor, define the field with ``editable=False`` (See `Django model field reference (editable)`_ ). - -.. _Django model field reference (editable): https://docs.djangoproject.com/en/dev/ref/models/fields/#editable - +Without a panel definition, a default form field (without label) will be used to represent your fields. If you intend to hide a field on the Wagtail page editor, define the field with :attr:`editable=False `. .. _inline_panels: diff --git a/docs/reference/signals.rst b/docs/reference/signals.rst index 9f7912d3ab..b4d37b2638 100644 --- a/docs/reference/signals.rst +++ b/docs/reference/signals.rst @@ -4,7 +4,7 @@ Signals ======= Wagtail's :ref:`page-revision-model-ref` and :ref:`page-model-ref` implement -`Signals `__ from ``django.dispatch``. +:doc:`Signals ` from ``django.dispatch``. Signals are useful for creating side-effects from page publish/unpublish events. For example, you could use signals to send publish notifications to a messaging service, or ``POST`` messages to another app that's consuming the API, such as a static site generator. @@ -71,7 +71,7 @@ wish to do something when a new blog post is published: Wagtail provides access to a list of registered page types through the ``get_page_models()`` function in ``wagtail.core.models``. -Read the `Django documentation `__ for more information about specifying senders. +Read the :ref:`Django documentation ` for more information about specifying senders. page_unpublished diff --git a/docs/topics/pages.rst b/docs/topics/pages.rst index e790f8dd29..2d00729176 100644 --- a/docs/topics/pages.rst +++ b/docs/topics/pages.rst @@ -4,15 +4,15 @@ Page models Each page type (a.k.a. content type) in Wagtail is represented by a Django model. All page models must inherit from the :class:`wagtail.core.models.Page` class. -As all page types are Django models, you can use any field type that Django provides. See `Model field reference `_ for a complete list of field types you can use. Wagtail also provides :class:`~wagtail.core.fields.RichTextField` which provides a WYSIWYG editor for editing rich-text content. +As all page types are Django models, you can use any field type that Django provides. See :doc:`Model field reference ` for a complete list of field types you can use. Wagtail also provides :class:`~wagtail.core.fields.RichTextField` which provides a WYSIWYG editor for editing rich-text content. .. topic:: Django models If you're not yet familiar with Django models, have a quick look at the following links to get you started: - * `Creating models `_ - * `Model syntax `_ + * :ref:`Creating models ` + * :doc:`Model syntax ` An example Wagtail page model @@ -256,7 +256,7 @@ You just need to create a template in a location where it can be accessed with t Template context ---------------- -Wagtail renders templates with the ``page`` variable bound to the page instance being rendered. Use this to access the content of the page. For example, to get the title of the current page, use ``{{ page.title }}``. All variables provided by `context processors `_ are also available. +Wagtail renders templates with the ``page`` variable bound to the page instance being rendered. Use this to access the content of the page. For example, to get the title of the current page, use ``{{ page.title }}``. All variables provided by :ref:`context processors ` are also available. Customising template context @@ -408,7 +408,7 @@ The first argument must match the value of the ``related_name`` attribute of the Working with pages ================== -Wagtail uses Django's `multi-table inheritance `_ feature to allow multiple page models to be used in the same tree. +Wagtail uses Django's :ref:`multi-table inheritance ` feature to allow multiple page models to be used in the same tree. Each page is added to both Wagtail's builtin :class:`~wagtail.core.models.Page` model as well as its user-defined model (such as the ``BlogPage`` model created earlier). diff --git a/docs/topics/permissions.rst b/docs/topics/permissions.rst index dafe94defc..d707a38017 100644 --- a/docs/topics/permissions.rst +++ b/docs/topics/permissions.rst @@ -4,7 +4,7 @@ Permissions =========== -Wagtail adapts and extends `the Django permission system `_ to cater for 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 :ref:`the Django permission system ` to cater for 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'. Page permissions diff --git a/docs/topics/snippets.rst b/docs/topics/snippets.rst index 6cf5df9020..912ddedd7f 100644 --- a/docs/topics/snippets.rst +++ b/docs/topics/snippets.rst @@ -42,12 +42,10 @@ The ``Advert`` model uses the basic Django model class and defines two propertie Including Snippets in Template Tags ----------------------------------- -The simplest way to make your snippets available to templates is with a template tag. This is mostly done with vanilla Django, so perhaps reviewing Django's documentation for `django custom template tags`_ will be more helpful. We'll go over the basics, though, and point out any considerations to make for Wagtail. +The simplest way to make your snippets available to templates is with a template tag. This is mostly done with vanilla Django, so perhaps reviewing Django's documentation for :doc:`django custom template tags ` will be more helpful. We'll go over the basics, though, and point out any considerations to make for Wagtail. First, add a new python file to a ``templatetags`` folder within your app - for example, ``myproject/demo/templatetags/demo_tags.py``. We'll need to load some Django modules and our app's models, and ready the ``register`` decorator: -.. _django custom template tags: https://docs.djangoproject.com/en/dev/howto/custom-template-tags/ - .. code-block:: python from django import template diff --git a/docs/topics/streamfield.rst b/docs/topics/streamfield.rst index a35ab80b5d..19e62e997f 100644 --- a/docs/topics/streamfield.rst +++ b/docs/topics/streamfield.rst @@ -217,7 +217,7 @@ ChoiceBlock A dropdown select box for choosing from a list of choices. The following keyword arguments are accepted: ``choices`` - A list of choices, in any format accepted by Django's ``choices`` parameter for model fields (https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices), or a callable returning such a list. + A list of choices, in any format accepted by Django's :attr:`~django.db.models.Field.choices` parameter for model fields, or a callable returning such a list. ``required`` (default: True) If true, the field cannot be left blank. @@ -951,7 +951,7 @@ As with any model field in Django, any changes to a model definition that affect To mitigate this, StructBlock, StreamBlock and ChoiceBlock implement additional logic to ensure that any subclasses of these blocks are deconstructed to plain instances of StructBlock, StreamBlock and ChoiceBlock -- in this way, the migrations avoid having any references to your custom class definitions. This is possible because these block types provide a standard pattern for inheritance, and know how to reconstruct the block definition for any subclass that follows that pattern. -If you subclass any other block class, such as ``FieldBlock``, you will need to either keep that class definition in place for the lifetime of your project, or implement a `custom deconstruct method `__ that expresses your block entirely in terms of classes that are guaranteed to remain in place. Similarly, if you customise a StructBlock, StreamBlock or ChoiceBlock subclass to the point where it can no longer be expressed as an instance of the basic block type -- for example, if you add extra arguments to the constructor -- you will need to provide your own ``deconstruct`` method. +If you subclass any other block class, such as ``FieldBlock``, you will need to either keep that class definition in place for the lifetime of your project, or implement a :ref:`custom deconstruct method ` that expresses your block entirely in terms of classes that are guaranteed to remain in place. Similarly, if you customise a StructBlock, StreamBlock or ChoiceBlock subclass to the point where it can no longer be expressed as an instance of the basic block type -- for example, if you add extra arguments to the constructor -- you will need to provide your own ``deconstruct`` method. .. _streamfield_migrating_richtext: diff --git a/docs/topics/writing_templates.rst b/docs/topics/writing_templates.rst index 140c608bf6..df7edb91f3 100644 --- a/docs/topics/writing_templates.rst +++ b/docs/topics/writing_templates.rst @@ -5,10 +5,10 @@ Writing templates ================= Wagtail uses Django's templating language. For developers new to Django, start with Django's own template documentation: -https://docs.djangoproject.com/en/dev/topics/templates/ +:doc:`django:topics/templates` Python programmers new to Django/Wagtail may prefer more technical documentation: -https://docs.djangoproject.com/en/dev/ref/templates/api/ +:doc:`ref/templates/api` You should be familiar with Django templating basics before continuing with this documentation. @@ -31,10 +31,7 @@ Template files are assumed to exist here:: models.py -For more information, see the Django documentation for the `application directories template loader`_. - -.. _application directories template loader: https://docs.djangoproject.com/en/dev/ref/templates/api/ - +For more information, see the Django documentation for the :doc:`application directories template loader `. Page content ~~~~~~~~~~~~ @@ -77,7 +74,7 @@ Read more about the image manipulation syntax here :ref:`image_tag`. Template tags & filters ======================= -In addition to Django's standard tags and filters, Wagtail provides some of its own, which can be ``load``-ed `just like any other `_. +In addition to Django's standard tags and filters, Wagtail provides some of its own, which can be ``load``-ed :doc:`just like any other `. Images (tag)