More docs

doc/web/storagebackends.rst

@@ -1,47 +1,19 @@
-.. _searchadapters:
+.. _storagebackends:
 
-.. currentmodule:: sphinx.websupport.search
+.. currentmodule:: sphinx.websupport.comments
 
-Search Adapters
-===============
+Storage Backends
+================
 
-To create a custom search adapter you will need to subclass the
-:class:`~BaseSearch` class. Then create an instance of the new class
-and pass that as the `search` keyword argument when you create the
-:class:`~sphinx.websupport.WebSupport` object::
+StorageBackend Methods
+~~~~~~~~~~~~~~~~~~~~~~
 
-   support = Websupport(srcdir=srcdir,
-                        outdir=outdir,
-			search=MySearch())
+.. automethod:: sphinx.websupport.comments.StorageBackend.pre_build
 
-For more information about creating a custom search adapter, please see
-the documentation of the :class:`BaseSearch` class below.
+.. automethod:: sphinx.websupport.comments.StorageBackend.add_node
 
-.. class:: BaseSearch
+.. automethod:: sphinx.websupport.comments.StorageBackend.post_build
 
-   Defines an interface for search adapters.
-
-BaseSearch Methods
-~~~~~~~~~~~~~~~~~~
-
-   The following methods are defined in the BaseSearch class. Some methods
-   do not need to be overridden, but some (
-   :meth:`~sphinx.websupport.search.BaseSearch.add_document` and
-   :meth:`~sphinx.websupport.search.BaseSearch.handle_query`) must be
-   overridden in your subclass. For a working example, look at the
-   built-in adapter for whoosh.
-
-.. automethod:: sphinx.websupport.search.BaseSearch.init_indexing
-
-.. automethod:: sphinx.websupport.search.BaseSearch.finish_indexing
-
-.. automethod:: sphinx.websupport.search.BaseSearch.feed
-
-.. automethod:: sphinx.websupport.search.BaseSearch.add_document
-
-.. automethod:: sphinx.websupport.search.BaseSearch.query
-
-.. automethod:: sphinx.websupport.search.BaseSearch.handle_query
-
-.. automethod:: sphinx.websupport.search.BaseSearch.extract_context
+.. automethod:: sphinx.websupport.comments.StorageBackend.add_comment
 
+.. automethod:: sphinx.websupport.comments.StorageBackend.get_comments

sphinx/websupport/comments/__init__.py

@@ -1,17 +1,35 @@
 
 class StorageBackend(object):
     def pre_build(self):
+        """Called immediately before the build process begins. Use this
+        to prepare the StorageBackend for the addition of nodes.
+        """
         pass
 
     def add_node(self, document, line, source, treeloc):
+        """Add a node to the StorageBackend.
+
+        `document` is the name of the document the node belongs to.
+        
+        `line` is the line in the source where the node begins.
+
+        `source` is the source files name.
+        
+        `treeloc` is for future use.
+        """
         raise NotImplemented
     
     def post_build(self):
+        """Called after a build has completed. Use this to finalize the
+        addition of nodes if needed.
+        """
         pass
 
     def add_comment(self, parent_id, text, displayed, username, 
                     rating, time):
+        """Called when a comment is being added."""
         raise NotImplemented
 
     def get_comments(self, parent_id):
+        """Called to retrieve all comments for a node."""
         raise NotImplemented

sphinx/websupport/comments/sqlalchemystorage.py

@@ -33,6 +33,8 @@ class SQLAlchemyStorage(StorageBackend):
         
         session = Session()
 
+        
+        
         id = parent_id[1:]
         if parent_id[0] == 's':
             node = session.query(Node).filter(Node.id == id).first()