Add reference docs for PageListingViewSet

docs/advanced_topics/customisation/custom_page_listings.md

@@ -1,8 +1,9 @@
+(custom_page_listings)=
 # Custom page listings
 
 Normally, editors navigate through the Wagtail admin interface by following the structure of the page tree. However, this can make it slow to locate a specific page for editing, especially on large sites where pages are organised into a deep hierarchy.
 
-Custom page listings are a way to present a flat list of all pages of a given type, accessed from a menu item in the Wagtail admin menu, with the ability for editors to search and filter this list to find the pages they are interested in.
+Custom page listings are a way to present a flat list of all pages of a given type, accessed from a menu item in the Wagtail admin menu, with the ability for editors to search and filter this list to find the pages they are interested in. To define a custom page listing, create a subclass of {class}`~wagtail.admin.viewsets.pages.PageListingViewSet` and register it using the [`register_admin_viewset`](register_admin_viewset) hook.
 
 For example, if your site implemented the page type `BlogPage`, you could provide a "Blog pages" listing in the Wagtail admin by adding the following definitions to a `wagtail_hooks.py` file within the app:
 

docs/reference/viewsets.md

@@ -218,3 +218,14 @@ Viewsets are Wagtail's mechanism for defining a group of related admin views wit
 .. autoclass:: wagtail.snippets.views.snippets.SnippetViewSetGroup
 
 ```
+
+## PageListingViewSet
+
+```{eval-rst}
+.. autoclass:: wagtail.admin.viewsets.pages.PageListingViewSet
+
+   .. autoattribute:: model
+   .. autoattribute:: index_view_class
+   .. autoattribute:: columns
+   .. autoattribute:: filterset_class
+```

wagtail/admin/viewsets/pages.py

@@ -7,10 +7,22 @@ from .base import ViewSet
 
 
 class PageListingViewSet(ViewSet):
+    """
+    A viewset to present a flat listing of all pages of a specific type.
+    All attributes and methods from :class:`~wagtail.admin.viewsets.base.ViewSet`
+    are available.
+    For more information on how to use this class, see :ref:`custom_page_listings`.
+    """
+
     #: The view class to use for the index view; must be a subclass of ``wagtail.admin.views.pages.listing.IndexView``.
     index_view_class = IndexView
+    #: Required; the page model class that this viewset will work with.
     model = Page
+    #: A list of ``wagtail.admin.ui.tables.Column`` instances for the columns in the listing.
     columns = IndexView.columns
+    #: A subclass of ``wagtail.admin.filters.WagtailFilterSet``, which is a
+    #: subclass of `django_filters.FilterSet <https://django-filter.readthedocs.io/en/stable/ref/filterset.html>`_.
+    #: This will be passed to the ``filterset_class`` attribute of the index view.
     filterset_class = IndexView.filterset_class
 
     def get_index_view_kwargs(self, **kwargs):