Lint docs with doc8

.circleci/config.yml

@@ -23,6 +23,7 @@ jobs:
       - run:
           shell: /bin/bash -e
           command: pipenv run jinjalint --parse-only wagtail | grep -v 'welcome_page.html:6:70' | tee /dev/tty | wc -l | grep -q '0'
+      - run: pipenv run doc8 --ignore D001 docs
       - run: DATABASE_NAME=wagtail.db pipenv run python -u runtests.py
 
   frontend:

docs/Makefile

@@ -59,6 +59,9 @@ spelling:
 	@echo
 	@echo "Spellcheck complete."
 
+lint:
+	doc8 --ignore D001 --ignore-path _build
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

docs/advanced_topics/adding_reports.rst

@@ -38,7 +38,7 @@ This retrieves the queryset of pages for your report. For our example:
 
 
     class UnpublishedChangesReportView(PageReportView):
-        
+
         def get_queryset(self):
             return Page.objects.filter(has_unpublished_changes=True)
 
@@ -106,7 +106,7 @@ preprocessing, set the preprocessing_function to ``None``.
 
 A dictionary of ``field_name`` strings mapping to ``{export_format: preprocessing_function}`` dictionaries,
 allowing custom preprocessing functions to be applied when exporting field values of specific classes (or their subclasses). This
-will take priority over functions specified in ``ReportView.custom_value_preprocess``. If unspecified (and 
+will take priority over functions specified in ``ReportView.custom_value_preprocess``. If unspecified (and
 ``ReportView.custom_value_preprocess`` also does not specify a function), ``force_str`` will be used. To prevent
 preprocessing, set the preprocessing_function to ``None``.
 
@@ -171,7 +171,7 @@ url for the report, you will need to use the ``register_admin_urls`` hook (see :
     @hooks.register('register_reports_menu_item')
     def register_unpublished_changes_report_menu_item():
         return AdminOnlyMenuItem("Pages with unpublished changes", reverse('unpublished_changes_report'), classnames='icon icon-' + UnpublishedChangesReportView.header_icon, order=700)
-    
+
     @hooks.register('register_admin_urls')
     def register_unpublished_changes_report_url():
         return [
@@ -201,7 +201,7 @@ The full code
 
         list_export = PageReportView.list_export + ['last_published_at']
         export_headings = dict(last_published_at='Last Published', **PageReportView.export_headings)
-        
+
         def get_queryset(self):
             return Page.objects.filter(has_unpublished_changes=True)
 
@@ -219,7 +219,7 @@ The full code
     @hooks.register('register_reports_menu_item')
     def register_unpublished_changes_report_menu_item():
         return AdminOnlyMenuItem("Pages with unpublished changes", reverse('unpublished_changes_report'), classnames='icon icon-' + UnpublishedChangesReportView.header_icon, order=700)
-    
+
     @hooks.register('register_admin_urls')
     def register_unpublished_changes_report_url():
         return [

docs/advanced_topics/customisation/custom_user_models.rst

@@ -12,7 +12,7 @@ Create a custom user model. This must at minimum inherit from ``AbstractBaseUser
 .. code-block:: python
 
   from django.contrib.auth.models import AbstractUser
-  
+
   class User(AbstractUser):
       country = models.CharField(verbose_name='country', max_length=255)
       status = models.ForeignKey(MembershipStatus, on_delete=models.SET_NULL, null=True, default=1)

docs/advanced_topics/deploying.rst

@@ -61,14 +61,14 @@ For Google Cloud Storage, create a ``cors.json`` configuration:
 
 .. code-block:: json
 
-	[
-	    {
-	      "origin": ["*"],
-	      "responseHeader": ["Content-Type"],
-	      "method": ["GET"],
-	      "maxAgeSeconds": 3600
-	    }
-	]
+    [
+        {
+          "origin": ["*"],
+          "responseHeader": ["Content-Type"],
+          "method": ["GET"],
+          "maxAgeSeconds": 3600
+        }
+    ]
 
 Then, apply this CORS configuration to the storage bucket:
 

docs/advanced_topics/i18n.rst

@@ -1,6 +1,6 @@
-====================	
-Internationalisation	
-====================	
+====================
+Internationalisation
+====================
 
 Multi-language content
 ======================
@@ -19,31 +19,31 @@ Several add-on packages for Wagtail providing multi-language support are availab
 For a comparison of these options, see AccordBox's blog post `How to support multi-language in Wagtail CMS <https://www.accordbox.com/blog/how-support-multi-language-wagtail-cms/>`_.
 
 
-Wagtail admin translations	
-==========================	
+Wagtail admin translations
+==========================
 
-The Wagtail admin backend has been translated into many different languages. You can find a list of currently available translations on Wagtail's `Transifex page <https://www.transifex.com/torchbox/wagtail/>`_. (Note: if you're using an old version of Wagtail, this page may not accurately reflect what languages you have available).	
+The Wagtail admin backend has been translated into many different languages. You can find a list of currently available translations on Wagtail's `Transifex page <https://www.transifex.com/torchbox/wagtail/>`_. (Note: if you're using an old version of Wagtail, this page may not accurately reflect what languages you have available).
 
-If your language isn't listed on that page, you can easily contribute new languages or correct mistakes. Sign up and submit changes to `Transifex <https://www.transifex.com/torchbox/wagtail/>`_. Translation updates are typically merged into an official release within one month of being submitted.	
+If your language isn't listed on that page, you can easily contribute new languages or correct mistakes. Sign up and submit changes to `Transifex <https://www.transifex.com/torchbox/wagtail/>`_. Translation updates are typically merged into an official release within one month of being submitted.
 
-Change Wagtail admin language on a per user basis	
-=================================================	
+Change Wagtail admin language on a per user basis
+=================================================
 
-Logged-in users can set their preferred language from ``/admin/account/``.	
-By default, Wagtail provides a list of languages that have a >= 90% translation coverage.	
-It is possible to override this list via the :ref:`WAGTAILADMIN_PERMITTED_LANGUAGES <WAGTAILADMIN_PERMITTED_LANGUAGES>` setting.	
+Logged-in users can set their preferred language from ``/admin/account/``.
+By default, Wagtail provides a list of languages that have a >= 90% translation coverage.
+It is possible to override this list via the :ref:`WAGTAILADMIN_PERMITTED_LANGUAGES <WAGTAILADMIN_PERMITTED_LANGUAGES>` setting.
 
-In case there is zero or one language permitted, the form will be hidden.	
+In case there is zero or one language permitted, the form will be hidden.
 
-If there is no language selected by the user, the ``LANGUAGE_CODE`` wil be used.	
+If there is no language selected by the user, the ``LANGUAGE_CODE`` wil be used.
 
 
-Changing the primary language of your Wagtail installation	
-==========================================================	
+Changing the primary language of your Wagtail installation
+==========================================================
 
-The default language of Wagtail is ``en-us`` (American English). You can change this by tweaking a couple of Django settings:	
+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 <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
 
-If there is a translation available for your language, the Wagtail admin backend should now be in the language you've chosen.
+If there is a translation available for your language, the Wagtail admin backend should now be in the language you've chosen.

docs/advanced_topics/images/feature_detection.rst

@@ -147,5 +147,5 @@ For example, you can manually run feature detection on all images by running the
         if not image.has_focal_point():
             image.set_focal_point(image.get_suggested_focal_point())
             image.save()
-            
-        
+
+

docs/advanced_topics/third_party_tutorials.rst

@@ -29,7 +29,7 @@ Third-party tutorials
 * `Wagtail and Azure storage blob containers <https://jossingram.wordpress.com/2017/11/29/wagtail-and-azure-storage-blob-containers/>`_ (29 November 2017)
 * `Building TwilioQuest with Twilio Sync, Django [incl. Wagtail], and Vue.js <https://www.twilio.com/blog/2017/11/building-twilioquest-with-twilio-sync-django-and-vue-js.html>`_ (6 November 2017)
 * `Image upload in wagtail forms <https://posts-by.lb.ee/image-uploads-in-wagtail-forms-3121c9b35d27>`_ (3 September 2017)
-* `Upgrading from Wagtail 1.0 to Wagtail 1.11 <https://www.caktusgroup.com/blog/2017/07/19/upgrading-wagtail/>`_ (19 July 2017) 
+* `Upgrading from Wagtail 1.0 to Wagtail 1.11 <https://www.caktusgroup.com/blog/2017/07/19/upgrading-wagtail/>`_ (19 July 2017)
 * `Wagtail-Multilingual: a simple project to demonstrate how multilingual is implemented <https://github.com/cristovao-alves/Wagtail-Multilingual>`_ (31 January 2017)
 * `Wagtail: 2 Steps for Adding Pages Outside of the CMS <https://www.caktusgroup.com/blog/2016/02/15/wagtail-2-steps-adding-pages-outside-cms/>`_ (15 February 2016)
 * `Adding a Twitter Widget for Wagtail’s new StreamField <https://jossingram.wordpress.com/2015/04/02/adding-a-twitter-widget-for-wagtails-new-streamfield/>`_ (2 April 2015)

docs/contributing/release_process.rst

@@ -159,7 +159,7 @@ Wagtail 1.4 will still support only Django 1.8 (LTS) and 1.9.
 Release process
 ===============
 
-Wagtail uses a `time-based release schedule <https://github.com/wagtail/wagtail/wiki/Release-schedule>`_, 
+Wagtail uses a `time-based release schedule <https://github.com/wagtail/wagtail/wiki/Release-schedule>`_,
 with feature releases every three months.
 
 After each feature release, the release manager will announce a timeline for

docs/editor_manual/administrator_tasks/managing_workflows.rst

@@ -24,7 +24,7 @@ _________________
 Under `Add tasks to your workflow`, you can add, remove, or reorder tasks in a workflow. When adding a task to a workflow, you will be given the
 option to create a new task, or reuse an existing one.
 
-Under `Assign your workflow to pages`, you can see a list of the pages to which the workflow has been assigned: any child pages will also have the same workflow, 
+Under `Assign your workflow to pages`, you can see a list of the pages to which the workflow has been assigned: any child pages will also have the same workflow,
 so if a workflow is assigned to the root page, it becomes the default workflow. You may remove it from pages using the `Delete` button to
 the right of each entry, or assign it to a page using the `Choose a page` button.
 
@@ -47,4 +47,4 @@ approve or reject moderation for this task.
 
 When editing a task, you may find that some fields - including the name - are uneditable. This is to ensure workflow history
 remains consistent - if you find yourself needing to change the name, it is recommended that you disable the old task, and create a new one with the name
-you need. Disabling a task will cause any pages currently in moderation on that task to skip to the next task.
+you need. Disabling a task will cause any pages currently in moderation on that task to skip to the next task.

docs/editor_manual/documents_images_snippets/documents.rst

@@ -18,4 +18,4 @@ Documents such as PDFs can be managed from the Documents interface, available in
 * Save or delete documents using the buttons at the bottom of the interface.
 
 .. Warning::
-    Deleted documents cannot be recovered. 
+    Deleted documents cannot be recovered.

docs/editor_manual/documents_images_snippets/images.rst

@@ -27,4 +27,4 @@ ___________
 * If your images are cropped in some way to make them fit to a specific shape, then the focal area will define the centre point from which the image is cropped.
 * To set the focal area, drag a marquee around the most important element of the image.
 * To remove the focal area, hit the button below the image.
-* If the feature is set up in your website, then on the front-end you will see the crop of this image focusing on your selection. 
+* If the feature is set up in your website, then on the front-end you will see the crop of this image focusing on your selection.

docs/editor_manual/documents_images_snippets/snippets.rst

@@ -36,4 +36,4 @@ If you are editing a page, and you find yourself in need of a new snippet, do no
 * You should now see your new snippet, even though you didn't leave the edit page.
 
 .. Note::
-    Even though this is possible, it is worth saving your page as a draft as often as possible, to avoid your changes being lost by navigating away from the edit page accidentally. 
+    Even though this is possible, it is worth saving your page as a draft as often as possible, to avoid your changes being lost by navigating away from the edit page accidentally.

docs/editor_manual/finding_your_way_around/using_search.rst

@@ -5,4 +5,4 @@ Using search
 
 * A very easy way to find the page that you want is to use the main search feature, accessible from the left-hand menu.
 * Simply type in part or all of the name of the page you are looking for, and the results below will automatically update as you type.
-* Clicking the page title in the results will take you to the Edit page for that result. You can differentiate between similar named pages using the Parent column, which tells you what the parent page of that page is.
+* Clicking the page title in the results will take you to the Edit page for that result. You can differentiate between similar named pages using the Parent column, which tells you what the parent page of that page is.

docs/editor_manual/intro.rst

@@ -10,4 +10,4 @@ This documentation will explain how to:
 -  modify, save, publish and unpublish pages
 -  how to set up users, and provide them with specific roles to create a publishing workflow
 -  upload, edit and include images and documents
--  ... and more!
+-  ... and more!

docs/editor_manual/new_pages/inserting_documents.rst

@@ -7,4 +7,4 @@ It is possible to insert links to documents held in the CMS into the body text o
 
 The process for doing this is the same as when inserting an image. You are given the choice of either choosing a document from the CMS, or uploading a new document.
 
-.. image:: ../../_static/images/screen28_docs_form.png
+.. image:: ../../_static/images/screen28_docs_form.png

docs/getting_started/integrating_into_django.rst

@@ -46,7 +46,7 @@ Add a ``STATIC_ROOT`` setting, if your project does not have one already:
 .. code-block:: python
 
     STATIC_ROOT = os.path.join(BASE_DIR, 'static')
-    
+
 Add ``MEDIA_ROOT`` and ``MEDIA_URL`` settings, if your project does not have these already:
 
 .. code-block:: python

docs/getting_started/the_zen_of_wagtail.rst

@@ -34,4 +34,4 @@ A common sight in content management systems is a point-and-click interface to l
 
 It looks nice in the sales pitch, but in reality, no CMS end-user can realistically make that kind of fundamental change - on a live site, no less - unless they have a programmer's insight into how the site is built, and what impact the change will have. As such, it will always be the programmer's job to negotiate that point-and-click interface - all you've done is taken them away from the comfortable world of writing code, where they have a whole ecosystem of tools, from text editors to version control systems, to help them develop, test and deploy their code changes.
 
-Wagtail recognises that most programming tasks are best done by writing code, and does not try to turn them into box-filling exercises when there's no good reason to. Likewise, when building functionality for your site, you should keep in mind that some features are destined to be maintained by the programmer rather than a content editor, and consider whether making them configurable through the Wagtail admin is going to be more of a hindrance than a convenience. For example, Wagtail provides a form builder to allow content authors to create general-purpose data collection forms. You might be tempted to use this as the basis for more complex forms that integrate with (for example) a CRM system or payment processor - however, in this case there's no way to edit the form fields without rewriting the backend logic, so making them editable through Wagtail has limited value. More likely, you'd be better off building these using Django's form framework, where the form fields are defined entirely in code.
+Wagtail recognises that most programming tasks are best done by writing code, and does not try to turn them into box-filling exercises when there's no good reason to. Likewise, when building functionality for your site, you should keep in mind that some features are destined to be maintained by the programmer rather than a content editor, and consider whether making them configurable through the Wagtail admin is going to be more of a hindrance than a convenience. For example, Wagtail provides a form builder to allow content authors to create general-purpose data collection forms. You might be tempted to use this as the basis for more complex forms that integrate with (for example) a CRM system or payment processor - however, in this case there's no way to edit the form fields without rewriting the backend logic, so making them editable through Wagtail has limited value. More likely, you'd be better off building these using Django's form framework, where the form fields are defined entirely in code.

docs/reference/contrib/frontendcache.rst

@@ -39,7 +39,7 @@ Add a new item into the ``WAGTAILFRONTENDCACHE`` setting and set the ``BACKEND``
             'LOCATION': 'http://localhost:8000',
         },
     }
-	WAGTAILFRONTENDCACHE_LANGUAGES = []
+    WAGTAILFRONTENDCACHE_LANGUAGES = []
 
 
 Set ``WAGTAILFRONTENDCACHE_LANGUAGES`` to a list of languages (typically equal to ``[l[0] for l in settings.LANGUAGES]``) to also purge the urls for each language of a purging url. This setting needs ``settings.USE_I18N`` to be ``True`` to work. Its default is an empty list.
@@ -57,7 +57,7 @@ Cloudflare
 
 Firstly, you need to register an account with Cloudflare if you haven't already got one. You can do this here: `Cloudflare Sign up <https://www.cloudflare.com/sign-up>`_
 
-Add an item into the ``WAGTAILFRONTENDCACHE`` and set the ``BACKEND`` parameter to ``wagtail.contrib.frontend_cache.backends.CloudflareBackend``. 
+Add an item into the ``WAGTAILFRONTENDCACHE`` and set the ``BACKEND`` parameter to ``wagtail.contrib.frontend_cache.backends.CloudflareBackend``.
 
 This backend can be configured to use an account-wide API key, or an API token with restricted access.
 

docs/reference/contrib/modeladmin/index.rst

@@ -12,7 +12,7 @@ Summary of features
 -------------------
 
 - A customisable list view, allowing you to control what values are displayed
-  for each row, available options for result filtering, default ordering, 
+  for each row, available options for result filtering, default ordering,
   spreadsheet downloads and more.
 - Access your list views from the Wagtail admin menu easily with automatically
   generated menu items, with automatic 'active item' highlighting. Control the

docs/reference/pages/panels.rst

@@ -306,7 +306,7 @@ Use ``classname="title"`` to make Page's built-in title field stand out with mor
 Placeholder Text
 ----------------
 
-By default, Wagtail uses the field's label as placeholder text. To change it, pass to the FieldPanel a widget with a placeholder attribute set to your desired text. You can select widgets from :doc:`Django's form widgets <django:ref/forms/widgets>`, or any of the Wagtail's widgets found in ``wagtail.admin.widgets``. 
+By default, Wagtail uses the field's label as placeholder text. To change it, pass to the FieldPanel a widget with a placeholder attribute set to your desired text. You can select widgets from :doc:`Django's form widgets <django:ref/forms/widgets>`, or any of the Wagtail's widgets found in ``wagtail.admin.widgets``.
 
 For example, to customize placeholders for a Book model exposed via ModelAdmin:
 
@@ -328,7 +328,7 @@ For example, to customize placeholders for a Book model exposed via ModelAdmin:
             }
         )
         # using the correct widget for your field type and desired effect
-        date_widget = widgets.AdminDateInput( 
+        date_widget = widgets.AdminDateInput(
             attrs = {
                 'placeholder': 'dd-mm-yyyy'
             }
@@ -336,7 +336,7 @@ For example, to customize placeholders for a Book model exposed via ModelAdmin:
 
         panels = [
             FieldPanel('title', widget=title_widget), # then add them as a variable
-            FieldPanel('release_date', widget=date_widget), 
+            FieldPanel('release_date', widget=date_widget),
             FieldPanel('price', widget=forms.NumberInput(attrs={'placeholder': 'Retail price on release'})) # or directly inline
         ]
 

docs/reference/settings.rst

@@ -592,7 +592,7 @@ Workflow
 
 Moderation workflows can be used in two modes. The first is to require that all tasks must approve a specific page revision for the workflow to complete. As a result,
 if edits are made to a page while it is in moderation, any approved tasks will need to be re-approved for the new revision before the workflow finishes.
-This is the default, ``WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT = True`` . The second mode does not require reapproval: if edits are made when 
+This is the default, ``WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT = True`` . The second mode does not require reapproval: if edits are made when
 tasks have already been approved, those tasks do not need to be reapproved. This is more suited to a hierarchical workflow system. To use workflows in this mode,
 set ``WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT = False``.
 
@@ -609,4 +609,4 @@ which publishes the page. The function must accept a ``WorkflowState`` object as
 
 This determines whether publishing a page with an ongoing workflow will cancel the workflow (if true) or leave the workflow unaffected (false).
 Disabling this could be useful if your site has long, multi-step workflows, and you want to be able to publish urgent page updates while the
-workflow continues to provide less urgent feedback. 
+workflow continues to provide less urgent feedback.

docs/releases/0.8.rst

@@ -92,7 +92,7 @@ and the ``validators`` attribute of the 'file' field - that is, the line:
 
 should become:
 
-    .. code-block:: python
+.. code-block:: python
 
     ('file', models.ImageField(upload_to=wagtail.wagtailimages.models.get_upload_to,
         width_field='width', height_field='height', verbose_name='File')),

docs/releases/2.9.rst

@@ -92,7 +92,7 @@ Django 2.1 is no longer supported as of this release; please upgrade to Django 2
 ``SiteMiddleware`` and ``request.site`` deprecated
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Wagtail's :class:`~wagtail.core.middleware.SiteMiddleware`, which makes the current site object available as the property ``request.site``, is now deprecated as it clashes with Django's sites framework and makes unnecessary database queries on non-Wagtail views. References to ``request.site`` in your code should be removed; the recommended way of retrieving the current site is ``Site.find_for_request(request)`` in Python code, and the ``{% wagtail_site %}`` tag within Django templates. 
+Wagtail's :class:`~wagtail.core.middleware.SiteMiddleware`, which makes the current site object available as the property ``request.site``, is now deprecated as it clashes with Django's sites framework and makes unnecessary database queries on non-Wagtail views. References to ``request.site`` in your code should be removed; the recommended way of retrieving the current site is ``Site.find_for_request(request)`` in Python code, and the ``{% wagtail_site %}`` tag within Django templates.
 
 For example:
 

docs/topics/search/backends.rst

@@ -119,7 +119,7 @@ Prerequisites are the `Elasticsearch`_ service itself and, via pip, the `elastic
 
 .. code-block:: sh
 
-  pip install "elasticsearch>=7.0.0,<8.0.0"  # for Elasticsearch 7.x  
+  pip install "elasticsearch>=7.0.0,<8.0.0"  # for Elasticsearch 7.x
 
 .. warning::
 

docs/topics/streamfield.rst

@@ -465,7 +465,7 @@ Alternatively, you can add ``form_classname`` in a subclass's ``Meta``:
 
         class Meta:
             form_classname = 'ingredients-list'
-    
+
 
 StreamBlock
 ~~~~~~~~~~~

setup.py

@@ -60,6 +60,7 @@ testing_extras = [
     'isort==4.2.5',
     'flake8-blind-except==0.1.1',
     'flake8-print==2.0.2',
+    'doc8==0.8.1',
 
     # For templates linting
     'jinjalint>=0.5',