From 7d34baf2d54d0441ffddf4942b99d30e6a58d25e Mon Sep 17 00:00:00 2001 From: Timo Stollenwerk Date: Wed, 25 Jan 2012 17:12:13 +0100 Subject: [PATCH] Prepare files for API documentation. --- docs/source/api.txt | 20 ++++------- docs/source/conf.py | 12 +++---- docs/source/email-notification.txt | 36 +++++++++---------- docs/source/workflow.txt | 50 +++++++++++++-------------- plone/app/discussion/comment.txt | 10 ++++++ plone/app/discussion/conversation.txt | 8 +++++ 6 files changed, 73 insertions(+), 63 deletions(-) create mode 100644 plone/app/discussion/comment.txt create mode 100644 plone/app/discussion/conversation.txt diff --git a/docs/source/api.txt b/docs/source/api.txt index 31819ab..6afad72 100644 --- a/docs/source/api.txt +++ b/docs/source/api.txt @@ -7,19 +7,11 @@ The conversation is responsible for storing all comments. It provides a dict-like API for accessing comments, where keys are integers and values are IComment objects. It also provides features for finding comments quickly. -The IReplies adapter provides an API for finding and manipulating the comments -directly in reply to a particular comment (implemented by the CommentReplies -adpater) or at the top level of the conversation (implemented by the -ConversationReplies adapter). +The IReplies adapter provides an API for finding and manipulating the comments +directly in reply to a particular comment (implemented by the CommentReplies +adpater) or at the top level of the conversation (implemented by the +ConversationReplies adapter). -.. autointerface:: plone.app.discussion.interfaces.IConversation - :members: +.. include:: ../../plone/app/discussion/conversation.txt -.. autointerface:: plone.app.discussion.interfaces.IReplies - :members: - -.. autointerface:: plone.app.discussion.interfaces.IComment - :members: - - - \ No newline at end of file +.. include:: ../../plone/app/discussion/comment.txt diff --git a/docs/source/conf.py b/docs/source/conf.py index 08ca111..d792a2a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -22,13 +22,13 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', 'repoze.sphinx.autointerface',] - + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/source/email-notification.txt b/docs/source/email-notification.txt index 6b5c709..883ceef 100644 --- a/docs/source/email-notification.txt +++ b/docs/source/email-notification.txt @@ -8,25 +8,25 @@ This document describes the plone.app.discussion email notification feature. Introduction ============ -plone.app.discussion allows users and administrators to be notified about new +plone.app.discussion allows users and administrators to be notified about new comments by email. There are two kinds of email notification: 1) **User notification**: Tell users when a comment has been added. - - This method composes and sends emails to all users that have added a comment + + This method composes and sends emails to all users that have added a comment to this conversation and enabled user notification. - - This requires the user_notification setting to be enabled in the discussion - control panel. - - + + This requires the user_notification setting to be enabled in the discussion + control panel. + + 2) **Moderator notification**: Tell the moderator when a comment needs attention. - + This method sends an email to the site admin (mail control panel setting) if comment moderation is enabled and a new comment has been added that needs to - be approved. - - This requires the moderator_notification to be enabled in the discussion + be approved. + + This requires the moderator_notification to be enabled in the discussion control panel and the comment_review_workflow enabled for the comment content type. @@ -60,16 +60,16 @@ Moderator Notification Event Subscribers ================= -Email notifications are triggered by event subscribers that are called when a +Email notifications are triggered by event subscribers that are called when a comment has been added to a page. .. note:: - In Plone 3, the event subscribers were located in the zope.lifecycleevent - package. They moved to zope.app.container in Plone 4. Therefore - plone.app.discussion registers one of the two subscribers, dependent on the - Plone version. + In Plone 3, the event subscribers were located in the zope.lifecycleevent + package. They moved to zope.app.container in Plone 4. Therefore + plone.app.discussion registers one of the two subscribers, dependent on the + Plone version. -To create custom email notifications, register a new event subscriber or +To create custom email notifications, register a new event subscriber or override an existing one. *plone/app/discussion/notifications.zcml* diff --git a/docs/source/workflow.txt b/docs/source/workflow.txt index 3e37b91..33fbf8e 100644 --- a/docs/source/workflow.txt +++ b/docs/source/workflow.txt @@ -2,14 +2,14 @@ Permissions and Workflows ========================= -This document describes how plone.app.discussion handles permissions and +This document describes how plone.app.discussion handles permissions and workflows. Introduction ============ -plone.app.discussion uses permissions and workflows to control what a user is +plone.app.discussion uses permissions and workflows to control what a user is allowed to do. It tries to use the default Plone permissions and workflow engine as much as possible. @@ -17,77 +17,77 @@ engine as much as possible. Permissions =========== -plone.app.discussion knows two permissions to control what a user is allowed to -do. The 'Reply to item' permission to control who is allowed to post a comment -on a content object and the 'Review comments' permission to control who is +plone.app.discussion knows two permissions to control what a user is allowed to +do. The 'Reply to item' permission to control who is allowed to post a comment +on a content object and the 'Review comments' permission to control who is allowed to review comments. 1) **Permission to post a comment**: The permission to post a comment is controlled by the 'Reply to item' - permission. By default, this permission is granted to the 'Member', + permission. By default, this permission is granted to the 'Member', 'Reviewer', and 'Manager' role. 2) **Permission to review comments**: - The permission to review comments is controlled by the 'Review comments' + The permission to review comments is controlled by the 'Review comments' permission. By default, this permission is granted to the 'Reviewer' and 'Manager' role. Changing permissions -------------------- -If you want to change the way plone.app.discussion allows users to post or +If you want to change the way plone.app.discussion allows users to post or review comments you can do that by changing which permissions are granted to which rules. In Plone permissions are always granted to roles, not to users directly. -For instance, if you want to allow users without the 'Member' role to post -comments, you have to grant the 'Reply to item' permission to the +For instance, if you want to allow users without the 'Member' role to post +comments, you have to grant the 'Reply to item' permission to the 'Authenticated' role. -Or, if you don't want to allow 'Reviewers' to review comments anymore, you +Or, if you don't want to allow 'Reviewers' to review comments anymore, you can just remove the 'Review comments' permission from the 'Reviewer' role. .. note:: For a general introduction to permissions and roles in Plone see: http://plone.org/documentation/kb/understanding-permissions/permissions-and-roles - + http://plone.org/products/dexterity/documentation/manual/developer-manual/advanced/permissions Workflows ========= -plone.app.discussion ships with a simple one-state +plone.app.discussion ships with a simple one-state workflow and a review workflow for comments: -1) **Comment Single State Workflow**: +1) **Comment Single State Workflow**: - Essentially a workflow with no transitions, but it has a published state, + Essentially a workflow with no transitions, but it has a published state, so portlets and applications that expect that state will continue to work. 2) **Comment Review Workflow**: A simple review workflow for comments - + A simple review workflow that comes with two states (pending and published) and a single transition (publish). - + The 'pending' state is the initial state. 'published' is the state where the comment is visible to everyone and non-editable. - + The 'publish' transition is protected by the 'Review comments' permission. - + :: - + * --> [pending] -- {publish} --> [published]--> * -.. note:: For a general introduction to workflows in Plone see: +.. note:: For a general introduction to workflows in Plone see: http://plone.org/documentation/kb/creating-workflows-in-plone/ Custom comment workflow ----------------------- -You can create and enable any custom workflow on the "comment" content type. +You can create and enable any custom workflow on the "comment" content type. Though, there are some special hooks in plone.app.discussion that check if the workflow that is enabled for the "comment" content type has a 'pending' state in order to do the following things: @@ -95,12 +95,12 @@ order to do the following things: 1) A portal message will be shown to the user after posting a comment, if the comment just entered the 'pending' state. - 2) A message is shown to the user if he/she accesses the bulk moderation view + 2) A message is shown to the user if he/she accesses the bulk moderation view and workflow is enabled for comments that does not implement a 'pending' state. 3) A moderator will only be emailed when comment moderation is enabled in the discussion control panel and the comment workflow contains a 'pending' - state. + state. + - diff --git a/plone/app/discussion/comment.txt b/plone/app/discussion/comment.txt new file mode 100644 index 0000000..436b0e9 --- /dev/null +++ b/plone/app/discussion/comment.txt @@ -0,0 +1,10 @@ +Comment +======= + +.. literalinclude:: ../../plone/app/discussion/interfaces.py + :language: python + :pyobject: IComment + + +.. autointerface:: plone.app.discussion.interfaces.IComment + :members: diff --git a/plone/app/discussion/conversation.txt b/plone/app/discussion/conversation.txt new file mode 100644 index 0000000..d14a05c --- /dev/null +++ b/plone/app/discussion/conversation.txt @@ -0,0 +1,8 @@ +Conversation +============ + +.. autointerface:: plone.app.discussion.interfaces.IConversation + :members: + +.. autointerface:: plone.app.discussion.interfaces.IReplies + :members: