Inline comments for the base model

bakerydemo/base/models.py

@@ -33,10 +33,12 @@ class BasePageFieldsMixin(models.Model):
         related_name='+',
         help_text='Landscape mode only; horizontal width between 1000px and 3000px.'
     )
+    # The StreamField is defined within base/blocks.py
     body = StreamField(
         BaseStreamBlock(), verbose_name="Page body", blank=True
     )
-
+    # The content_panels makes the fields accessible to the editor within the
+    # admin area. If you don't include a field here it won't be displayed
     content_panels = Page.content_panels + [
         FieldPanel('introduction', classname="full"),
         ImageChooserPanel('image'),
@@ -50,8 +52,14 @@ class BasePageFieldsMixin(models.Model):
 @register_snippet
 class People(ClusterableModel):
     """
-    `People` snippets are secondary content objects that do not require their
-    own full webpage to render.
+    A Django model to store People objects.
+    It uses the `@register_snippet` decorator to allow it to be accessible
+    as via the Snippets UI (e.g. /admin/snippets/base/people/)
+
+    `People` uses the `ClusterableModel`, which allows the relationship to another
+    model (e.g. a PageModel) to be stored independently of the database. This
+    allows us to preview foreignKey relationships without first saving the parent
+    https://github.com/wagtail/django-modelcluster
     """
     first_name = models.CharField("First name", max_length=254)
     last_name = models.CharField("Last name", max_length=254)
@@ -79,8 +87,8 @@ class People(ClusterableModel):
 
     @property
     def thumb_image(self):
-        # fail silently if there is no profile pic or the rendition file can't
-        # be found. Note @richbrennan worked out how to do this...
+        # Return an empty string if there is no profile pic or the rendition
+        # file can't be found.
         try:
             return self.image.get_rendition('fill-50x50').img_tag()
         except:
@@ -97,7 +105,10 @@ class People(ClusterableModel):
 @register_snippet
 class FooterText(models.Model):
     """
-    This provides editable text for the site footer
+    This provides editable text for the site footer. Again it uses the decorator
+    `register_snippet` to allow it to be accessible via the admin. It is made
+    accessible on the template via a template tag defined in base/templatetags/
+    navigation_tags.py
     """
     body = RichTextField()
 
@@ -114,8 +125,8 @@ class FooterText(models.Model):
 
 class StandardPage(Page, BasePageFieldsMixin):
     """
-    A fairly generic site page, to be used for About, etc.
-    Defines no fields of its own - just a wrapper for the fields defined in BasePageFieldsMixin.
+    A generic content page. On this demo site we use it for an about page but
+    could be used for any type of page content.
     """
 
     # Inherit the content panels from BasePageFieldsMixin
@@ -124,8 +135,16 @@ class StandardPage(Page, BasePageFieldsMixin):
 
 class HomePage(Page):
     """
-    The Home Page
+    The Home Page. This looks slightly more complicated than it is. You can
+    see if you visit your site and edit the homepage that it is split between
+    a:
+    - Hero area
+    - Body area
+    - A promotional area
+    - Moveable featured site sections
     """
+
+    # Hero section of HomePage
     image = models.ForeignKey(
         'wagtailimages.Image',
         null=True,
@@ -153,10 +172,12 @@ class HomePage(Page):
         help_text='Choose a page to link to for the Call to Action'
     )
 
+    # Body section of the HomePage
     body = StreamField(
         BaseStreamBlock(), verbose_name="Home content block", blank=True
     )
 
+    # Promo section of the HomePage
     promo_image = models.ForeignKey(
         'wagtailimages.Image',
         null=True,
@@ -177,6 +198,11 @@ class HomePage(Page):
         help_text='Write some promotional copy'
     )
 
+    # Featured sections on the HomePage
+    # You will see on templates/base/home_page.html that these are treated
+    # in different ways, and displayed in different areas of the page.
+    # Each list their children items that we access via the children function
+    # that we define on the individual Page models e.g. BlogIndexPage
     featured_section_1_title = models.CharField(
         null=True,
         blank=True,
@@ -262,7 +288,10 @@ class HomePage(Page):
 
 class GalleryPage(BasePageFieldsMixin, Page):
     """
-    This is a page to list locations from the selected Collection
+    This is a page to list locations from the selected Collection. We use a Q
+    object to list any Collection created (/admin/collections/) even if they
+    contain no items. It's unlikely to be useful for many production settings
+    but is intended to show the extensibility of aspect of Wagtail
     """
     collection = models.ForeignKey(
         Collection,
@@ -283,6 +312,14 @@ class GalleryPage(BasePageFieldsMixin, Page):
 
 
 class FormField(AbstractFormField):
+    """
+    Wagtailforms is a module to introduce simple forms on a Wagtail site. It
+    isn't intended as a replacement to Django's form support but as a quick way
+    to generate general purpose data-collection form without having to write
+    code. We use it on the site for a contact form. You can read more about
+    Wagtail forms at:
+    http://docs.wagtail.io/en/v1.9/reference/contrib/forms/index.html
+    """
     page = ParentalKey('FormPage', related_name='form_fields')
 
 
@@ -296,6 +333,9 @@ class FormPage(AbstractEmailForm):
     )
     body = StreamField(BaseStreamBlock())
     thank_you_text = RichTextField(blank=True)
+
+    # Note how we include the FormField object via an InlinePanel using the
+    # related_name value
     content_panels = AbstractEmailForm.content_panels + [
         ImageChooserPanel('image'),
         StreamFieldPanel('body'),