Sphinx-based developer documentation added.

svn path=/plone.app.discussion/trunk/; revision=35523

CHANGES.txt

@@ -4,6 +4,10 @@ Changelog
 1.0b4 (unreleased)
 ------------------
 
+* Sphinx-based developer documentation added. See 
+  http://packages.python.org/plone.app.discussion.
+  [timo]
+
 * Rename "Single State Workflow" to "Comment Single State Workflow".
   [timo]
 

docs/source/api.txt

@@ -1,8 +1,25 @@
-API
----
+API/Interfaces
+--------------
 
-.. automodule:: plone.app.discussion
+The conversation and replies adapters.
 
-    .. autoclass:: plone.app.discussion.conversation.Conversation
+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.
 
-        .. automethod:: plone.app.discussion.conversation.Conversation.enabled
+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:
+
+.. autointerface:: plone.app.discussion.interfaces.IReplies
+   :members:
+   
+.. autointerface:: plone.app.discussion.interfaces.IComment
+   :members:
+   
+   
+   

docs/source/architecture.txt

@@ -10,7 +10,7 @@ plone.app.discussion.
     CMF and Plone UI constructs.
 
   **Discussion items are cataloged**
-    It is be possible to search for discussion items like any other type of
+    It is possible to search for discussion items like any other type of
     content.
 
   **Discussion items are subject to workflow and permission**
@@ -19,26 +19,26 @@ plone.app.discussion.
     permissions.
 
   **Discussion items are light weight objects**
-    Discussion item objects are as light weight as possible. 
-    Ideally, a discussion item should be as lightweight as a catalog brain.
-    This may mean that we forego convenience base classes and re-implement
-    certain interfaces. Comments should not provide the full set of dublin
-    core metadata, though custom indexers can be used to provide values for
-    standard catalog indexes.
+    Discussion item objects are as light weight as possible. Ideally, a 
+    discussion item should be as lightweight as a catalog brain. This may mean 
+    that we forego convenience base classes and re-implement certain interfaces. 
+    Comments should not provide the full set of dublin core metadata, though 
+    custom indexers can be used to provide values for standard catalog indexes.
 
   **Optimise for retrival speed**
     HTML filtering and other processing should happen on save, not on render,
     to make rendering quick.
 
   **Settings are stored using plone.registry** 
-    Any global setting should be stored in plone.registry records
+    Any global setting should be stored in plone.registry records.
     
   **Forms are constructed using extensible z3c.form forms**
     This allows plugins (such as spam protection algorithms) to provide
-    additional validation
+    additional validation. It also allows integrators to write add-ons that add
+    new fields to the comment form.
 
   **Discussion items are stored in a BTree container**
-    This allows faster lookup and manipulation
+    This allows faster lookup and manipulation.
 
   **Discussion items are accessed using a dict-like interface**
     This makes iteration and manipulation more natural. Even if comments are

docs/source/conf.py

@@ -22,7 +22,8 @@ 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']

docs/source/design.txt

@@ -150,20 +150,18 @@ an auto-moderation 'white-list', e.g. by email address or username.
 Forms and UI
 ------------
 
-The basic commenting display/reply form should be placed in a viewlet.
+The basic commenting display/reply form is placed in a viewlet.
 
-Ideally, the reply form should be inline, perhaps revealed with JavaScript
-if enabled. This allows full contextualisation of replies. The current
-solution, with a separate form that shows some context, is brittle and
-over-complicated.
+The reply form is dynamically created right under the comment when the user hits
+the reply button. To do so, we copy the standard comment form with a jQuery 
+function. This function sets the form's hidden in_reply_to field to the id of
+the comment the user wants to reply to. This also makes is possible to use 
+z3c.form validation for the reply forms, because we can uniquely identify the 
+a reply form request and return the reply form with validation errors.
 
-If we support quoting of comments in replies, we can load the text to quote
-using JavaScript as well.
+Since we rely on JavaScript for the reply form creation, the reply button is
+removed for nonJavaScript enabled browsers.
 
-As a fall-back for non-JavaScript enabled browsers, it is probably OK not to
-support quoting and/or viewing of context, e.g. the user is taken to a standalone
-'comment reply' form.
-
-All actual forms should be handled using z3c.form and plone.z3cform's
-ExtensibleForm support. This makes it possible to plug in additional fields
-declaratively, e.g. to include spam protection.
+The comment form uses z3c.form and plone.z3cform's ExtensibleForm support. This 
+makes it possible to plug in additional fields declaratively, e.g. to include 
+SPAM protection.

setup.cfg

@@ -0,0 +1,7 @@
+[build_sphinx]
+source-dir = docs/source
+build-dir  = docs
+all_files  = 1
+
+[upload_sphinx]
+upload-dir = docs/html