some cube documentation with a screenshot

__pkginfo__.py

@@ -8,7 +8,7 @@
 version = '.'.join(str(num) for num in numversion)
 
 license = 'LGPL'
-copyright = '''Copyright (c) 2003-2009 LOGILAB S.A. (Paris, FRANCE).
+copyright = '''Copyright (c) 2003-2010 LOGILAB S.A. (Paris, FRANCE).
 http://www.logilab.fr/ -- mailto:contact@logilab.fr'''
 
 author = "Logilab"
@@ -16,5 +16,19 @@
 web = 'http://www.cubicweb.org/project/%s' % distname
 
 short_desc = "comment component for the CubicWeb framework"
-long_desc = """This CubicWeb component provides threadable comments.
+long_desc = """\
+Summary
+-------
+
+The `comment` cube provides threadable comments feature.
+
+Screenshots
+-----------
+
+Threadable comment view:
+
+.. image:: cube_comment1.png
+
+Usage
+-----
 
@@ -20,5 +34,28 @@
 
-CubicWeb is a semantic web framework, see http://www.cubicweb.org
+This cube creates a new entity type called `Comment` which could basically be
+read by every body but only added by application's users.
+It also defines a relation `comments` which provides the ability to add a
+`Comment` which `comments` a `Comment`.
+
+To use this cube, you want to add the relation `comments` on the entity type
+you want to be able to comment. For instance, let's say your cube defines a
+schema for a blog. You want all the blog entries to be commentable.
+Here is how to define it in your schema:
+
+.. sourcecode:: python
+
+    class Blog(EntityType):
+        title = String(maxsize=50, required=True)
+        description = RichString()
+
+    class BlogEntry(EntityType):
+        title = String(required=True, fulltextindexed=True, maxsize=256)
+        content = RichString(required=True, fulltextindexed=True)
+        entry_of = SubjectRelation('Blog', cardinality='**')
+        comments = ObjectRelation('Comment', cardinality='1*')
+
+Once this relation is defined, you can post comments and view threadable
+comments.
 """
 
 from os import listdir