Add documentation for commenting

docs/editor_manual/editing_existing_pages.rst

@@ -12,6 +12,7 @@ Here is how you can access the edit screen of an existing page:
 * When editing an existing page the title of the page being edited is displayed at the top of the page.
 * Underneath the title, you can find the page type and a link to the page history.
 * If published, a link to the live version of the page is shown on the top right.
+* You can toggle commenting mode by clicking the icon in the top right, which also shows the number of comments.
 * You can change the title of the page by clicking into the title field.
 * When you're typing into a field, help text is often displayed on the right-hand side of the screen.
 
@@ -27,3 +28,46 @@ show more information about the page's progress through the workflow, as well as
 If you can perform moderation actions (for example, approval or requesting changes) on the current task, you'll see additional options in the
 action menu at the bottom of the page.
 
+.. _commenting:
+
+Commenting
+__________
+
+Use the comment icon at the top right to enable commenting mode. If there are comments on the page, the number
+of comments is shown alongside the icon.
+
+When in commenting mode, hovering over a commentable field or block will reveal a comment button.
+
+.. image:: ../_static/images/screen49_new_comment_icon.png
+
+If there is no pre-existing comment on the field, you can use this to create a new comment.
+
+.. image:: ../_static/images/screen52_new_comment.png
+
+If there is an existing comment, clicking either the field button or the comment will bring the comment thread into focus, allowing you to
+add new replies.
+
+.. image:: ../_static/images/screen48_comment_thread.png
+
+Within a rich text field, you can highlight text and click the comment button to add an inline comment.
+
+.. image:: ../_static/images/screen51_draftail_comment.png
+
+All of these actions can also be performed using the comment shortcut, ``Ctrl + Alt + M`` / ``⌘ + Alt + M``.
+
+Clicking the three dots in the top right of an existing comment will open its menu. This allows you to
+resolve a comment, as well as to edit or delete any of your own comments.
+
+.. image:: ../_static/images/screen50_comment_menu.png
+
+Any comments or changes to comments will only be saved when the page is saved.
+
+.. note:: Currently, fields inside ``InlinePanels`` and ``ListBlocks`` are uncommentable.
+
+The arrow to the right of the comments icon shows the comment notifications
+panel, where you can enable or disable email notifications for other users' comments on the page.
+
+.. image:: ../_static/images/screen53_commenting_notifications.png
+
+.. note:: You will always receive email notifications for threads you are part of, unless you opt out of all comment notifications in your
+        account settings.

docs/reference/pages/model_reference.rst

@@ -1031,3 +1031,147 @@ Database fields
         (foreign key to :class:`PageRevision`)
 
         A foreign key to the current page revision.
+
+
+
+``Comment``
+===========
+
+Represents a comment on a page.
+
+Database fields
+~~~~~~~~~~~~~~~
+
+.. class:: Comment
+
+    .. attribute:: page
+
+        (parental key to :class:`Page`)
+
+        A parental key to the page the comment has been added to.
+
+    .. attribute:: user
+
+        (foreign key to user model)
+
+        A foreign key to the user who added this comment.
+
+    .. attribute:: text
+
+        (text)
+
+        The text content of the comment.
+
+    .. attribute:: contentpath
+
+        (text)
+
+        The path to the field or streamfield block the comment is attached to,
+        in the form ``field`` or ``field.streamfield_block_id``.
+
+    .. attribute:: position
+
+        (text)
+
+        An identifier for the position of the comment within its field. The format
+        used is determined by the field.
+
+    .. attribute:: created_at
+
+        (date/time)
+
+        The date/time when the comment was created.
+
+    .. attribute:: updated_at
+
+        (date/time)
+
+        The date/time when the comment was updated.
+
+    .. attribute:: revision_created
+
+        (foreign key to :class:`PageRevision`)
+
+        A foreign key to the revision on which the comment was created.
+
+    .. attribute:: resolved_at
+
+        (date/time)
+
+        The date/time when the comment was resolved, if any.
+
+    .. attribute:: resolved_by
+
+        (foreign key to user model)
+
+        A foreign key to the user who resolved this comment, if any.
+
+
+
+``CommentReply``
+================
+
+Represents a reply to a comment thread.
+
+Database fields
+~~~~~~~~~~~~~~~
+
+.. class:: CommentReply
+
+    .. attribute:: comment
+
+        (parental key to :class:`Comment`)
+
+        A parental key to the comment that started the thread.
+
+    .. attribute:: user
+
+        (foreign key to user model)
+
+        A foreign key to the user who added this comment.
+
+    .. attribute:: text
+
+        (text)
+
+        The text content of the comment.
+
+    .. attribute:: created_at
+
+        (date/time)
+
+        The date/time when the comment was created.
+
+    .. attribute:: updated_at
+
+        (date/time)
+
+        The date/time when the comment was updated.
+
+
+
+``PageSubscription``
+====================
+
+Represents a user's subscription to email notifications about page events.
+Currently only used for comment notifications.
+
+Database fields
+~~~~~~~~~~~~~~~
+
+.. class:: PageSubscription
+
+    .. attribute:: page
+
+        (parental key to :class:`Page`)
+
+    .. attribute:: user
+
+        (foreign key to user model)
+
+    .. attribute:: comment_notifications
+
+        (boolean)
+
+        Whether the user should receive comment notifications for all comments,
+        or just comments in threads they participate in.

docs/reference/pages/panels.rst

@@ -15,7 +15,7 @@ Here are some Wagtail-specific types that you might include as fields in your mo
 FieldPanel
 ~~~~~~~~~~
 
-.. class:: FieldPanel(field_name, classname=None, widget=None, heading='')
+.. class:: FieldPanel(field_name, classname=None, widget=None, heading='', disable_comments=False)
 
     This is the panel used for basic Django field types.
 
@@ -39,6 +39,10 @@ FieldPanel
 
         This allows you to override the heading for the panel, which will otherwise be set automatically using the form field's label (taken in turn from a model field's ``verbose_name``).
 
+    .. attribute:: FieldPanel.disable_comments (optional)
+
+        This allows you to prevent a field level comment button showing for this panel if set to ``True`` (see :ref:`commenting`).
+
 StreamFieldPanel
 ~~~~~~~~~~~~~~~~
 

docs/releases/2.13.rst

@@ -29,7 +29,7 @@ This module was contributed by Coen van der Kamp.
 Commenting
 ~~~~~~~~~~
 
-The page editor now supports leaving comments on fields and StreamField blocks, by entering commenting mode (using the button in the top right of the editor). Inline comments are available in rich text fields using the Draftail editor.
+The page editor now supports :ref:`leaving comments on fields and StreamField blocks <commenting>`, by entering commenting mode (using the button in the top right of the editor). Inline comments are available in rich text fields using the Draftail editor.
 
 This feature was developed by Jacob Topp-Mugglestone, Karl Hobley and Simon Evans and sponsored by `The Motley Fool <https://www.fool.com/>`_.