Sphinx-based developer documentation added.

svn path=/plone.app.discussion/trunk/; revision=35523
This commit is contained in:
Timo Stollenwerk 2010-03-24 07:56:53 +00:00
parent 1be96fa588
commit 23fae2b6f9
13 changed files with 57 additions and 30 deletions

View File

@ -4,6 +4,10 @@ Changelog
1.0b4 (unreleased) 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". * Rename "Single State Workflow" to "Comment Single State Workflow".
[timo] [timo]

BIN
docs/doctrees/api.doctree Normal file

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

View File

@ -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:

View File

@ -10,7 +10,7 @@ plone.app.discussion.
CMF and Plone UI constructs. CMF and Plone UI constructs.
**Discussion items are cataloged** **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. content.
**Discussion items are subject to workflow and permission** **Discussion items are subject to workflow and permission**
@ -19,26 +19,26 @@ plone.app.discussion.
permissions. permissions.
**Discussion items are light weight objects** **Discussion items are light weight objects**
Discussion item objects are as light weight as possible. Discussion item objects are as light weight as possible. Ideally, a
Ideally, a discussion item should be as lightweight as a catalog brain. discussion item should be as lightweight as a catalog brain. This may mean
This may mean that we forego convenience base classes and re-implement that we forego convenience base classes and re-implement certain interfaces.
certain interfaces. Comments should not provide the full set of dublin Comments should not provide the full set of dublin core metadata, though
core metadata, though custom indexers can be used to provide values for custom indexers can be used to provide values for standard catalog indexes.
standard catalog indexes.
**Optimise for retrival speed** **Optimise for retrival speed**
HTML filtering and other processing should happen on save, not on render, HTML filtering and other processing should happen on save, not on render,
to make rendering quick. to make rendering quick.
**Settings are stored using plone.registry** **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** **Forms are constructed using extensible z3c.form forms**
This allows plugins (such as spam protection algorithms) to provide 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** **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** **Discussion items are accessed using a dict-like interface**
This makes iteration and manipulation more natural. Even if comments are This makes iteration and manipulation more natural. Even if comments are

View File

@ -22,7 +22,8 @@ import sys, os
# Add any Sphinx extension module names here, as strings. They can be extensions # Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # 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. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']

View File

@ -150,20 +150,18 @@ an auto-moderation 'white-list', e.g. by email address or username.
Forms and UI 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 The reply form is dynamically created right under the comment when the user hits
if enabled. This allows full contextualisation of replies. The current the reply button. To do so, we copy the standard comment form with a jQuery
solution, with a separate form that shows some context, is brittle and function. This function sets the form's hidden in_reply_to field to the id of
over-complicated. 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 Since we rely on JavaScript for the reply form creation, the reply button is
using JavaScript as well. removed for nonJavaScript enabled browsers.
As a fall-back for non-JavaScript enabled browsers, it is probably OK not to The comment form uses z3c.form and plone.z3cform's ExtensibleForm support. This
support quoting and/or viewing of context, e.g. the user is taken to a standalone makes it possible to plug in additional fields declaratively, e.g. to include
'comment reply' form. SPAM protection.
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.

7
setup.cfg Normal file
View File

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