Documentation for ModelViewSet

docs/extending/generic_views.md

@@ -3,3 +3,46 @@ Generic views
 
 Wagtail provides a number of generic views for handling common tasks such as creating / editing model instances, and chooser modals. Since these often involve several related views with shared properties (such as the model that we're working with, and its associated icon) Wagtail also implements the concept of a _viewset_, which allows a bundle of views to be defined collectively, and their URLs to be registered with the admin app as a single operation through the `register_admin_viewset` hook.
 
+ModelViewSet
+------------
+
+The `wagtail.admin.viewsets.model.ModelViewSet` class provides the views for listing, creating, editing and deleting model instances. For example, if we have the following model:
+
+```python
+from django.db import models
+
+class Person(models.Model):
+    first_name = models.CharField(max_length=255)
+    last_name = models.CharField(max_length=255)
+
+    def __str__(self):
+        return "%s %s" % (self.first_name, self.last_name)
+```
+
+The following definition (to be placed in the same app's `views.py`) will generate a set of views for managing Person instances:
+
+```python
+from wagtail.admin.viewsets.model import ModelViewSet
+from .models import Person
+
+
+class PersonViewSet(ModelViewSet):
+    model = Person
+    form_fields = ["first_name", "last_name"]
+    icon = "user"
+```
+
+This viewset can then be registered with the Wagtail admin to make it available under the URL `/admin/person/`, by adding the following to `wagtail_hooks.py`:
+
+```python
+from wagtail import hooks
+
+from .views import PersonViewSet
+
+
+@hooks.register("register_admin_viewset")
+def register_viewset():
+    return PersonViewSet("person")
+```
+
+Various additional attributes are available to customise the viewset - see [](../reference/viewsets).

docs/reference/viewsets.md

@@ -4,7 +4,7 @@ Viewsets are Wagtail's mechanism for defining a group of related admin views wit
 
 ```{eval-rst}
 
-Viewset
+ViewSet
 -------
 
 .. autoclass:: wagtail.admin.viewsets.base.ViewSet
@@ -12,4 +12,29 @@ Viewset
    .. automethod:: on_register
    .. automethod:: get_urlpatterns
    .. automethod:: get_url_name
+
+ModelViewSet
+------------
+
+.. autoclass:: wagtail.admin.viewsets.model.ModelViewSet
+
+   .. attribute:: model
+
+   Required; the model class that this viewset will work with.
+
+   .. attribute:: form_fields
+
+   A list of model field names that should be included in the create / edit forms.
+
+   .. attribute:: exclude_form_fields
+
+   Used in place of ``form_fields`` to indicate that all of the model's fields except the ones listed here should appear in the create / edit forms. Either ``form_fields`` or ``exclude_form_fields`` must be supplied (unless ``get_form_class`` is being overridden).
+
+   .. automethod:: get_form_class
+
+   .. autoattribute:: icon
+   .. autoattribute:: index_view_class
+   .. autoattribute:: add_view_class
+   .. autoattribute:: edit_view_class
+   .. autoattribute:: delete_view_class
 ```

wagtail/admin/viewsets/model.py

@@ -13,11 +13,22 @@ from .base import ViewSet
 
 
 class ModelViewSet(ViewSet):
-    icon = ""
+    """
+    A viewset to allow listing, creating, editing and deleting model instances.
+    """
 
+    icon = ""  #: The icon to use to represent the model within this viewset.
+
+    #: The view class to use for the index view; must be a subclass of ``wagtail.admin.views.generic.IndexView``.
     index_view_class = generic.IndexView
+
+    #: The view class to use for the create view; must be a subclass of ``wagtail.admin.views.generic.CreateView``.
     add_view_class = generic.CreateView
+
+    #: The view class to use for the edit view; must be a subclass of ``wagtail.admin.views.generic.EditView``.
     edit_view_class = generic.EditView
+
+    #: The view class to use for the delete view; must be a subclass of ``wagtail.admin.views.generic.DeleteView``.
     delete_view_class = generic.DeleteView
 
     @property
@@ -73,6 +84,9 @@ class ModelViewSet(ViewSet):
         return db_field.formfield(**kwargs)
 
     def get_form_class(self, for_update=False):
+        """
+        Returns the form class to use for the create / edit forms.
+        """
         fields = getattr(self, "form_fields", None)
         exclude = getattr(self, "exclude_form_fields", None)