Restructured basic panels docs

docs/reference/pages/editing_api.rst

@@ -20,18 +20,62 @@ A "panel" is the basic editing block in Wagtail. Wagtail will automatically pick
 
 There are four basic types of panels:
 
-  ``FieldPanel( field_name, classname=None, widget=None )``
+.. module:: wagtail.wagtailadmin.edit_handers
-    This is the panel used for basic Django field types. ``field_name`` is the name of the class property used in your model definition. ``classname`` is a string of optional CSS classes given to the panel which are used in formatting and scripted interactivity. By default, panels are formatted as inset fields. The CSS class ``full`` can be used to format the panel so it covers the full width of the Wagtail page editor. The CSS class ``title`` can be used to mark a field as the source for auto-generated slug strings. The optional ``widget`` parameter allows you to specify a `django form widget`_ to use instead of the default widget for this field type.
+
+FieldPanel
+----------
+
+.. class:: FieldPanel(field_name, classname=None, widget=None)
+
+    This is the panel used for basic Django field types.
+
+    .. attribute:: FieldPanel.field_name
+
+        This is the name of the class property used in your model definition.
+
+    .. attribute:: FieldPanel.classname
+
+        This is a string of optional CSS classes given to the panel which are used in formatting and scripted interactivity. By default, panels are formatted as inset fields.
+
+        The CSS class ``full`` can be used to format the panel so it covers the full width of the Wagtail page editor.
+
+        The CSS class ``title`` can be used to mark a field as the source for auto-generated slug strings.
+
+    .. attribute:: FieldPanel.widget (optional)
+
+        This parameter allows you to specify a `django form widget`_ to use instead of the default widget for this field type.
 
 .. _django form widget: https://docs.djangoproject.com/en/dev/ref/forms/widgets/
 
-  ``MultiFieldPanel( children, heading="", classname=None )``
+MultiFieldPanel
-    This panel condenses several ``FieldPanel`` s or choosers, from a list or tuple, under a single ``heading`` string.
+---------------
 
-  ``InlinePanel( relation_name, panels=None, classname=None, label='', help_text='' )``
+.. class:: MultiFieldPanel(children, heading="", classname=None)
-    This panel allows for the creation of a "cluster" of related objects over a join to a separate model, such as a list of related links or slides to an image carousel. This is a very powerful, but tricky feature which will take some space to cover, so we'll skip over it for now. For a full explanation on the usage of ``InlinePanel``, see :ref:`inline_panels`.
+
+    This panel condenses several ``FieldPanel`` s or choosers, from a ``list`` or ``tuple``, under a single ``heading`` string.
+
+    .. attribute:: MultiFieldPanel.children
+
+        A ``list`` or ``tuple`` of child panels
+
+    .. attribute:: MultiFieldPanel.heading
+
+        A heading for the fields
+
+InlinePanel
+-----------
+
+.. class:: InlinePanel(relation_name, panels=None, classname=None, label='', help_text='')
+
+    This panel allows for the creation of a "cluster" of related objects over a join to a separate model, such as a list of related links or slides to an image carousel.
+
+    This is a very powerful, but tricky feature which will take some space to cover, so we'll skip over it for now. For a full explanation on the usage of ``InlinePanel``, see :ref:`inline_panels`.
+
+FieldRowPanel
+-------------
+
+.. class:: FieldRowPanel(children, classname=None)
 
-  ``FieldRowPanel( children, classname=None )``
     This panel is purely aesthetic. It creates a columnar layout in the editing interface, where each of the child Panels appears alongside each other rather than below. Use of FieldRowPanel particularly helps reduce the "snow-blindness" effect of seeing so many fields on the page, for complex models. It also improves the perceived association between fields of a similar nature. For example if you created a model representing an "Event" which had a starting date and ending date, it may be intuitive to find the start and end date on the same "row".
 
     FieldRowPanel should be used in combination with ``col*`` classnames added to each of the child Panels of the FieldRowPanel. The Wagtail editing interface is layed out using a grid system, in which the maximum width of the editor is 12 columns wide. Classes ``col1``-``col12`` can be applied to each child of a FieldRowPanel. The class ``col3`` will ensure that field appears 3 columns wide or a quarter the width. ``col4`` would cause the field to be 4 columns wide, or a third the width.