documentation - adopt MyST syntax for form builder section

- the original conversion to markdown happened around the same time as the MyST conversion
- this meant that the syntax was not in sync
- also run prettier over markdown for consistent formatting & whitespace
- see #8007

docs/reference/contrib/forms/customisation.md

@@ -1,13 +1,11 @@
 # Form builder customisation
 
-```eval_rst
-For a basic usage example see :ref:`form_builder_usage`.
-```
+For a basic usage example see [form builder usage](form_builder_usage).
 
 ## Custom `related_name` for form fields
 
 If you want to change `related_name` for form fields
-(by default `AbstractForm` and `AbstractEmailForm` expect ``form_fields`` to be defined),
+(by default `AbstractForm` and `AbstractEmailForm` expect `form_fields` to be defined),
 you will need to override the `get_form_fields` method.
 You can do this as shown below.
 
@@ -51,8 +49,8 @@ class FormPage(AbstractEmailForm):
 If you need to save additional data, you can use a custom form submission model.
 To do this, you need to:
 
-* Define a model that extends `wagtail.contrib.forms.models.AbstractFormSubmission`.
-* Override the `get_submission_class` and `process_form_submission` methods in your page model.
+-   Define a model that extends `wagtail.contrib.forms.models.AbstractFormSubmission`.
+-   Override the `get_submission_class` and `process_form_submission` methods in your page model.
 
 Example:
 
@@ -110,8 +108,8 @@ class CustomFormSubmission(AbstractFormSubmission):
 
 If you want to add custom data to the CSV export, you will need to:
 
-* Override the `get_data_fields` method in page model.
-* Override `get_data` in the submission model.
+-   Override the `get_data_fields` method in page model.
+-   Override `get_data` in the submission model.
 
 The example below shows how to add a username to the CSV export.
 Note that this code also changes the submissions list view.
@@ -253,7 +251,6 @@ class CustomFormSubmission(AbstractFormSubmission):
         unique_together = ('page', 'user')
 ```
 
-
 Your template should look like this:
 
 ```html+django
@@ -283,7 +280,6 @@ Your template should look like this:
 </html>
 ```
 
-
 ## Multi-step form
 
 The following example shows how to create a multi-step form.
@@ -400,7 +396,6 @@ class FormPage(AbstractEmailForm):
         )
 ```
 
-
 Your template for this form page should look like this:
 
 ```html+django
@@ -422,7 +417,6 @@ Your template for this form page should look like this:
 </html>
 ```
 
-
 Note that the example shown before allows the user to return to a previous step,
 or to open a second step without submitting the first step.
 Depending on your requirements, you may need to add extra checks.
@@ -595,9 +589,7 @@ class FormPage(AbstractEmailForm):
 
 The Admin listing of form submissions can be customised by setting the attribute `submissions_list_view_class` on your FormPage model.
 
-```eval_rst
-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`.
-```
+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:
 
@@ -638,18 +630,17 @@ class FormPage(AbstractEmailForm):
 
 First, make the new field type available in the page editor by changing your `FormField` model.
 
-* Create a new set of choices which includes the original `FORM_FIELD_CHOICES` along with new field types you want to make available.
-* Each choice must contain a unique key and a human readable name of the field, e.g. `('slug', 'URL Slug')`
-* Override the `field_type` field in your `FormField` model with `choices` attribute using these choices.
-* You will need to run `./manage.py makemigrations` and `./manage.py migrate` after this step.
-
+-   Create a new set of choices which includes the original `FORM_FIELD_CHOICES` along with new field types you want to make available.
+-   Each choice must contain a unique key and a human readable name of the field, e.g. `('slug', 'URL Slug')`
+-   Override the `field_type` field in your `FormField` model with `choices` attribute using these choices.
+-   You will need to run `./manage.py makemigrations` and `./manage.py migrate` after this step.
 
 Then, create and use a new form builder class.
 
-* Define a new form builder class that extends the `FormBuilder` class.
-* Add a method that will return a created Django form field for the new field type.
-* Its name must be in the format: `create_<field_type_key>_field`, e.g. `create_slug_field`
-* Override the `form_builder` attribute in your form page model to use your new form builder class.
+-   Define a new form builder class that extends the `FormBuilder` class.
+-   Add a method that will return a created Django form field for the new field type.
+-   Its name must be in the format: `create_<field_type_key>_field`, e.g. `create_slug_field`
+-   Override the `form_builder` attribute in your form page model to use your new form builder class.
 
 Example:
 
@@ -693,20 +684,16 @@ class FormPage(AbstractEmailForm):
     form_builder = CustomFormBuilder
 ```
 
-
-```eval_rst
-.. _form_builder_render_email:
-```
+(form_builder_render_email)=
 
 ## Custom `render_email` method
 
 If you want to change the content of the email that is sent when a form submits you can override the `render_email` method.
 
-
 To do this, you need to:
 
-* Ensure you have your form model defined that extends `wagtail.contrib.forms.models.AbstractEmailForm`.
-* Override the `render_email` method in your page model.
+-   Ensure you have your form model defined that extends `wagtail.contrib.forms.models.AbstractEmailForm`.
+-   Override the `render_email` method in your page model.
 
 Example:
 
@@ -741,18 +728,15 @@ class FormPage(AbstractEmailForm):
         return content
 ```
 
-
 ## Custom `send_mail` method
 
 If you want to change the subject or some other part of how an email is sent when a form submits you can override the `send_mail` method.
 
-
 To do this, you need to:
 
-* Ensure you have your form model defined that extends `wagtail.contrib.forms.models.AbstractEmailForm`.
-* In your models.py file, import the `wagtail.admin.mail.send_mail` function.
-* Override the `send_mail` method in your page model.
-
+-   Ensure you have your form model defined that extends `wagtail.contrib.forms.models.AbstractEmailForm`.
+-   In your models.py file, import the `wagtail.admin.mail.send_mail` function.
+-   Override the `send_mail` method in your page model.
 
 Example:
 

docs/reference/contrib/forms/index.md

@@ -1,19 +1,14 @@
-# Form builder
+(form_builder)=
 
-```eval_rst
-.. _form_builder:
-```
+# 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.
 
-```eval_rst
-.. note::
-  **wagtailforms is not a replacement for** :doc:`Django's form support <django:topics/forms/index>`. 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 <https://github.com/gasman/wagtail-form-example/commits/master>`_ for an example of integrating a Django form into a Wagtail page.
+```{note}
+**wagtailforms is not a replacement for** {doc}`Django's form support <django:topics/forms/index>`. 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](https://github.com/gasman/wagtail-form-example/commits/master) for an example of integrating a Django form into a Wagtail page.
 ```
 
-```eval_rst
-.. _form_builder_usage:
-```
+(form_builder_usage)=
 
 ## Usage
 
@@ -28,7 +23,6 @@ INSTALLED_APPS = [
 
 Within the `models.py` of one of your apps, create a model that extends `wagtail.contrib.forms.models.AbstractEmailForm`:
 
-
 ```python
 from django.db import models
 from modelcluster.fields import ParentalKey
@@ -64,10 +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/3.0/ref/settings/#short-date-format) and [SHORT_DATETIME_FORMAT](https://docs.djangoproject.com/en/3.0/ref/settings/#short-datetime-format) respectively.
-```eval_rst
-(see :ref:`form_builder_render_email` for how to customise the email content).
-```
+Date and datetime values in a form response will be formatted with the [SHORT_DATE_FORMAT](https://docs.djangoproject.com/en/3.0/ref/settings/#short-date-format) and [SHORT_DATETIME_FORMAT](https://docs.djangoproject.com/en/3.0/ref/settings/#short-datetime-format) respectively. (see [](form_builder_render_email) for how to customise 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.
 
@@ -93,10 +84,7 @@ You now need to create two templates named `form_page.html` and `form_page_landi
 
 `form_page_landing.html` is a standard Wagtail template, displayed after the user makes a successful form submission, `form_submission` will be available in this template. If you want to dynamically override the landing page template, you can do so with the `get_landing_page_template` method (in the same way that you would with `get_template`).
 
-
-```eval_rst
-.. _wagtailforms_formsubmissionpanel:
-```
+(wagtailforms_formsubmissionpanel)=
 
 ## Displaying form submission information
 
@@ -115,12 +103,12 @@ class FormPage(AbstractEmailForm):
     ]
 ```
 
-
 ## Index
 
-```eval_rst
-.. toctree::
-    :maxdepth: 1
-
-    customisation
+```{toctree}
+---
+maxdepth: 1
+titlesonly:
+---
+customisation
 ```