From 460874e11951815c3c96baf4ceaf79cfee5889cb Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Sun, 30 May 2010 20:52:24 -0500
Subject: [PATCH 001/127] Revert incomplete change in last revision.

---
 sphinx/cmdline.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py
index 8f8e6b313..e3e944656 100644
--- a/sphinx/cmdline.py
+++ b/sphinx/cmdline.py
@@ -21,7 +21,7 @@ from sphinx import __version__
 from sphinx.errors import SphinxError
 from sphinx.application import Sphinx
 from sphinx.util import Tee, format_exception_cut_frames, save_traceback
-from sphinx.util.console import red, nocolor, init_color
+from sphinx.util.console import red, nocolor, color_terminal
 
 
 def usage(argv, msg=None):
@@ -57,7 +57,10 @@ Modi:
 
 
 def main(argv):
-    init_color()
+    if not color_terminal():
+        # Windows' poor cmd box doesn't understand ANSI sequences
+        nocolor()
+
     try:
         opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:ng:NEqQWw:P')
         allopts = set(opt[0] for opt in opts)

From 099a58e0b7b37b0737c83253fda5b1ff344bdec2 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Sun, 30 May 2010 21:33:04 -0500
Subject: [PATCH 002/127] "Initial commit": Added sphinx.websupport module, as
 well as a builder and writer for the web support package.

---
 CHANGES.jacobmason            |  2 ++
 sphinx/builders/__init__.py   |  1 +
 sphinx/builders/websupport.py | 56 +++++++++++++++++++++++++++++++++++
 sphinx/websupport/__init__.py | 14 +++++++++
 sphinx/websupport/api.py      | 40 +++++++++++++++++++++++++
 sphinx/websupport/document.py | 37 +++++++++++++++++++++++
 sphinx/writers/websupport.py  | 29 ++++++++++++++++++
 7 files changed, 179 insertions(+)
 create mode 100644 CHANGES.jacobmason
 create mode 100644 sphinx/builders/websupport.py
 create mode 100644 sphinx/websupport/__init__.py
 create mode 100644 sphinx/websupport/api.py
 create mode 100644 sphinx/websupport/document.py
 create mode 100644 sphinx/writers/websupport.py

diff --git a/CHANGES.jacobmason b/CHANGES.jacobmason
new file mode 100644
index 000000000..42adc4270
--- /dev/null
+++ b/CHANGES.jacobmason
@@ -0,0 +1,2 @@
+May 30: Added files builders/websupport.py, writers/websupport.py,
+websupport/api.py, and websupport/document.api. Provides a rudimentary method of building websupport data, and rendering it as html.
\ No newline at end of file
diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py
index e345d570f..328b26683 100644
--- a/sphinx/builders/__init__.py
+++ b/sphinx/builders/__init__.py
@@ -329,4 +329,5 @@ BUILTIN_BUILDERS = {
     'man':        ('manpage', 'ManualPageBuilder'),
     'changes':    ('changes', 'ChangesBuilder'),
     'linkcheck':  ('linkcheck', 'CheckExternalLinksBuilder'),
+    'websupport': ('websupport', 'WebSupportBuilder'),
 }
diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
new file mode 100644
index 000000000..d39bbd6de
--- /dev/null
+++ b/sphinx/builders/websupport.py
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.builders.websupport
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Builder for the web support package.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from os import path
+
+from sphinx.util.osutil import ensuredir, os_path
+from sphinx.builders.html import PickleHTMLBuilder
+from sphinx.writers.websupport import WebSupportTranslator
+
+class WebSupportBuilder(PickleHTMLBuilder):
+    """
+    Builds documents for the web support package.
+    """
+    name = 'websupport'
+    template_suffix = '.html'
+    
+    def init_translator_class(self):
+        self.translator_class = WebSupportTranslator
+        
+    def write_doc(self, docname, doctree):
+        # The translator needs the docuname to generate ids.
+        self.docname = docname
+        PickleHTMLBuilder.write_doc(self, docname, doctree)
+
+    def handle_page(self, pagename, ctx, templatename='', **ignored):
+        # Mostly copied from PickleHTMLBuilder.
+        ctx['current_page_name'] = pagename
+        self.add_sidebars(pagename, ctx)
+
+        self.app.emit('html-page-context', pagename, ctx)
+
+        # Instead of pickling ctx as PickleHTMLBuilder does, we
+        # create a Document object and pickle that.
+        document = self.docwriter.visitor.support_document
+        document.body = ctx['body'] if 'body' in ctx else ''
+        document.title = ctx['title'] if 'title' in ctx else ''
+
+        doc_filename = path.join(self.outdir,
+                                 os_path(pagename) + self.out_suffix)
+        ensuredir(path.dirname(doc_filename))
+        f = open(doc_filename, 'wb')
+        try:
+            self.implementation.dump(document, f, 2)
+        finally:
+            f.close()
+
+    def get_target_uri(self, docname, typ=None):
+        return docname
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
new file mode 100644
index 000000000..36c2dcc91
--- /dev/null
+++ b/sphinx/websupport/__init__.py
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport
+    ~~~~~~~~~~~~~~~~~
+
+    Web Support Package
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from sphinx.websupport.api import WebSupport
+
+support = WebSupport()
diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
new file mode 100644
index 000000000..da6fc9e1f
--- /dev/null
+++ b/sphinx/websupport/api.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.api
+    ~~~~~~~~~~~~~~~~~~~~
+
+    All API functions.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import cPickle as pickle
+from os import path
+
+from jinja2 import Template
+
+from sphinx.application import Sphinx
+
+class WebSupport(object):
+    
+    def init(self, srcdir, outdir='', comment_html=''):
+        self.srcdir = srcdir
+        self.outdir = outdir or os.path.join(self.srcdir, '_build',
+                                             'websupport')
+        self.comment_template = Template(comment_html)
+
+    def build(self, **kwargs):
+        doctreedir = kwargs.pop('doctreedir', 
+                                path.join(self.outdir, 'doctrees'))
+        app = Sphinx(self.srcdir, self.srcdir,
+                     self.outdir, doctreedir, 'websupport')
+        app.build()
+
+    def get_document(self, docname):
+        infilename = path.join(self.outdir, docname + '.fpickle')
+        f = open(infilename, 'rb')
+        document = pickle.load(f)
+        # The document renders the comment_template.
+        document.comment_template = self.comment_template
+        return document
diff --git a/sphinx/websupport/document.py b/sphinx/websupport/document.py
new file mode 100644
index 000000000..d1f5677bb
--- /dev/null
+++ b/sphinx/websupport/document.py
@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.document
+    ~~~~~~~~~~~~~~~~~~~~
+
+    Contains a Document class for working with Sphinx documents.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from os import path
+
+from jinja2 import Template
+from docutils import nodes
+from sphinx import addnodes
+
+class Document(object):
+    """A single Document such as 'index'."""
+    def __init__(self):
+        self.commentable_nodes = []
+        self.template = None
+
+    def add_commentable(self, node_id, rst_source=''):
+        node = CommentableNode(node_id, rst_source)
+
+    def render_comment(self, id):
+        return self.comment_template.render(id=id)
+
+    def render_html(self, comments=False):
+        template = Template(self.body)
+        return template.render(render_comment=self.render_comment)
+
+class CommentableNode(object):
+    def __init__(self, id, rst_source=''):
+        self.id = id
+        self.rst_source=''
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
new file mode 100644
index 000000000..3b2507558
--- /dev/null
+++ b/sphinx/writers/websupport.py
@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.writers.websupport
+    ~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    docutils writers handling Sphinx' custom nodes.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from sphinx.writers.html import HTMLTranslator
+from sphinx.websupport.document import Document
+
+class WebSupportTranslator(HTMLTranslator):
+    """
+    Our custom HTML translator.
+    """
+    def __init__(self, builder, *args, **kwargs):
+        HTMLTranslator.__init__(self, builder, *args, **kwargs)
+        self.support_document = Document()
+        self.current_id = 0
+
+    def depart_paragraph(self, node):
+        HTMLTranslator.depart_paragraph(self, node)
+        self.support_document.add_commentable(self.current_id)
+        self.body.append("{{ render_comment('%s-p%s') }}" % 
+                         (self.builder.docname, self.current_id))
+        self.current_id += 1

From 0e26a6d46c1a61378b57d042968500032ba41a48 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Sun, 30 May 2010 22:20:59 -0500
Subject: [PATCH 003/127] Fixed bad call to os.path

---
 sphinx/websupport/api.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index da6fc9e1f..3cf112a30 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -20,8 +20,8 @@ class WebSupport(object):
     
     def init(self, srcdir, outdir='', comment_html=''):
         self.srcdir = srcdir
-        self.outdir = outdir or os.path.join(self.srcdir, '_build',
-                                             'websupport')
+        self.outdir = outdir or path.join(self.srcdir, '_build',
+                                          'websupport')
         self.comment_template = Template(comment_html)
 
     def build(self, **kwargs):

From 777386ef566a88246f6c4cadeba88fc79cc71d56 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Mon, 31 May 2010 16:07:47 -0500
Subject: [PATCH 004/127] Switched to creating a list of html slices

---
 sphinx/builders/websupport.py |  6 ++----
 sphinx/websupport/api.py      |  7 +------
 sphinx/websupport/document.py | 22 ++++++++--------------
 sphinx/writers/websupport.py  | 23 +++++++++++++++++++----
 4 files changed, 30 insertions(+), 28 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index d39bbd6de..f6b64849c 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -26,7 +26,7 @@ class WebSupportBuilder(PickleHTMLBuilder):
         self.translator_class = WebSupportTranslator
         
     def write_doc(self, docname, doctree):
-        # The translator needs the docuname to generate ids.
+        # The translator needs the docname to generate ids.
         self.docname = docname
         PickleHTMLBuilder.write_doc(self, docname, doctree)
 
@@ -38,10 +38,8 @@ class WebSupportBuilder(PickleHTMLBuilder):
         self.app.emit('html-page-context', pagename, ctx)
 
         # Instead of pickling ctx as PickleHTMLBuilder does, we
-        # create a Document object and pickle that.
+        # have created a Document object and pickle that.
         document = self.docwriter.visitor.support_document
-        document.body = ctx['body'] if 'body' in ctx else ''
-        document.title = ctx['title'] if 'title' in ctx else ''
 
         doc_filename = path.join(self.outdir,
                                  os_path(pagename) + self.out_suffix)
diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index 3cf112a30..eca24fb5e 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -12,17 +12,14 @@
 import cPickle as pickle
 from os import path
 
-from jinja2 import Template
-
 from sphinx.application import Sphinx
 
 class WebSupport(object):
     
-    def init(self, srcdir, outdir='', comment_html=''):
+    def init(self, srcdir, outdir=''):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
-        self.comment_template = Template(comment_html)
 
     def build(self, **kwargs):
         doctreedir = kwargs.pop('doctreedir', 
@@ -35,6 +32,4 @@ class WebSupport(object):
         infilename = path.join(self.outdir, docname + '.fpickle')
         f = open(infilename, 'rb')
         document = pickle.load(f)
-        # The document renders the comment_template.
-        document.comment_template = self.comment_template
         return document
diff --git a/sphinx/websupport/document.py b/sphinx/websupport/document.py
index d1f5677bb..16a60934b 100644
--- a/sphinx/websupport/document.py
+++ b/sphinx/websupport/document.py
@@ -18,20 +18,14 @@ from sphinx import addnodes
 class Document(object):
     """A single Document such as 'index'."""
     def __init__(self):
-        self.commentable_nodes = []
-        self.template = None
+        self.slices = []
 
-    def add_commentable(self, node_id, rst_source=''):
-        node = CommentableNode(node_id, rst_source)
+    def add_slice(self, html, id=None, commentable=False):
+        slice = HTMLSlice(html, id, commentable)
+        self.slices.append(slice)
 
-    def render_comment(self, id):
-        return self.comment_template.render(id=id)
-
-    def render_html(self, comments=False):
-        template = Template(self.body)
-        return template.render(render_comment=self.render_comment)
-
-class CommentableNode(object):
-    def __init__(self, id, rst_source=''):
+class HTMLSlice(object):
+    def __init__(self, html, id, commentable):
+        self.html = html
         self.id = id
-        self.rst_source=''
+        self.commentable = commentable
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 3b2507558..e712b1339 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -18,12 +18,27 @@ class WebSupportTranslator(HTMLTranslator):
     """
     def __init__(self, builder, *args, **kwargs):
         HTMLTranslator.__init__(self, builder, *args, **kwargs)
+        self.init_support()
+
+    def init_support(self):
         self.support_document = Document()
         self.current_id = 0
+        
+    def handle_visit_commentable(self, node):
+        self.support_document.add_slice(''.join(self.body))
+        self.body = []
+
+    def handle_depart_commentable(self, node):
+        slice_id = '%s-%s' % (self.builder.docname, self.current_id)
+        self.support_document.add_slice(''.join(self.body),
+                                        slice_id, commentable=True)
+        self.body = []
+        self.current_id += 1
+
+    def visit_paragraph(self, node):
+        HTMLTranslator.visit_paragraph(self, node)
+        self.handle_visit_commentable(node)
 
     def depart_paragraph(self, node):
         HTMLTranslator.depart_paragraph(self, node)
-        self.support_document.add_commentable(self.current_id)
-        self.body.append("{{ render_comment('%s-p%s') }}" % 
-                         (self.builder.docname, self.current_id))
-        self.current_id += 1
+        self.handle_depart_commentable(node)

From 9e81b8f003f0b0d055189367c1a701048796644a Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Mon, 31 May 2010 17:12:32 -0500
Subject: [PATCH 005/127] Slice at bullet_list, desc, or paragraph now.

---
 sphinx/writers/websupport.py | 43 +++++++++++++++++++++++++-----------
 1 file changed, 30 insertions(+), 13 deletions(-)

diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index e712b1339..a1e59788c 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -16,29 +16,46 @@ class WebSupportTranslator(HTMLTranslator):
     """
     Our custom HTML translator.
     """
+    commentable_nodes = ['bullet_list', 'paragraph', 'desc']
+
     def __init__(self, builder, *args, **kwargs):
         HTMLTranslator.__init__(self, builder, *args, **kwargs)
         self.init_support()
 
     def init_support(self):
         self.support_document = Document()
+        self.in_commentable = False
         self.current_id = 0
         
+    def dispatch_visit(self, node):
+        if node.__class__.__name__ in self.commentable_nodes:
+            self.handle_visit_commentable(node)
+        HTMLTranslator.dispatch_visit(self, node)
+
+    def dispatch_departure(self, node):
+        HTMLTranslator.dispatch_departure(self, node)
+        if node.__class__.__name__ in self.commentable_nodes:
+            self.handle_depart_commentable(node)
+
     def handle_visit_commentable(self, node):
-        self.support_document.add_slice(''.join(self.body))
-        self.body = []
+        # If we are already recording a commentable slice we don't do
+        # anything. We can't handle nesting.
+        if not self.in_commentable:
+            self.support_document.add_slice(''.join(self.body))
+            node.commented = self.in_commentable = True
+            self.body = []
+        else:
+            node.commented = False
 
     def handle_depart_commentable(self, node):
-        slice_id = '%s-%s' % (self.builder.docname, self.current_id)
-        self.support_document.add_slice(''.join(self.body),
-                                        slice_id, commentable=True)
-        self.body = []
-        self.current_id += 1
+        assert(self.in_commentable)
+        if node.commented:
+            slice_id = '%s-%s' % (self.builder.docname, self.current_id)
+            self.current_id += 1
 
-    def visit_paragraph(self, node):
-        HTMLTranslator.visit_paragraph(self, node)
-        self.handle_visit_commentable(node)
+            body = ''.join(self.body)
+            self.support_document.add_slice(body, slice_id, commentable=True)
+
+            self.in_commentable = False
+            self.body = []
 
-    def depart_paragraph(self, node):
-        HTMLTranslator.depart_paragraph(self, node)
-        self.handle_depart_commentable(node)

From c894c38cd35a05a763655bfaccaa64212e4895c8 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Wed, 2 Jun 2010 19:16:12 -0500
Subject: [PATCH 006/127] Fixed bug that clipped the end of bodies.

---
 sphinx/writers/websupport.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index a1e59788c..6d255e64c 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -59,3 +59,8 @@ class WebSupportTranslator(HTMLTranslator):
             self.in_commentable = False
             self.body = []
 
+    def depart_document(self, node):
+        assert(not self.in_commentable)
+        self.support_document.add_slice(''.join(self.body))
+                
+

From e6c4d8f75235dbdef0fc5c7d13b707d3f372b1c4 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Wed, 2 Jun 2010 19:22:33 -0500
Subject: [PATCH 007/127] Added ctx to document.

---
 sphinx/builders/websupport.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index f6b64849c..48e895db5 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -32,7 +32,7 @@ class WebSupportBuilder(PickleHTMLBuilder):
 
     def handle_page(self, pagename, ctx, templatename='', **ignored):
         # Mostly copied from PickleHTMLBuilder.
-        ctx['current_page_name'] = pagename
+        ctx['current_page_name'] = ctx['pagename'] = pagename
         self.add_sidebars(pagename, ctx)
 
         self.app.emit('html-page-context', pagename, ctx)
@@ -40,13 +40,14 @@ class WebSupportBuilder(PickleHTMLBuilder):
         # Instead of pickling ctx as PickleHTMLBuilder does, we
         # have created a Document object and pickle that.
         document = self.docwriter.visitor.support_document
+        document.__dict__.update(ctx)
 
         doc_filename = path.join(self.outdir,
                                  os_path(pagename) + self.out_suffix)
         ensuredir(path.dirname(doc_filename))
         f = open(doc_filename, 'wb')
         try:
-            self.implementation.dump(document, f, 2)
+            self.implementation.dump(document, f)
         finally:
             f.close()
 

From 4627e2a498b66603fa0304627a724dd82976f7c3 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Fri, 4 Jun 2010 16:12:29 -0500
Subject: [PATCH 008/127] Made srcdir a kwarg.

---
 sphinx/websupport/api.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index eca24fb5e..0d2722d66 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -16,7 +16,7 @@ from sphinx.application import Sphinx
 
 class WebSupport(object):
     
-    def init(self, srcdir, outdir=''):
+    def init(self, srcdir='', outdir=''):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')

From 65ac358d80c477172fa5e8a51ff0f8b0276514cb Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Fri, 4 Jun 2010 16:13:53 -0500
Subject: [PATCH 009/127] rough documentation

---
 doc/contents.rst       |  1 +
 doc/web/api.rst        | 26 +++++++++++++++
 doc/web/quickstart.rst | 72 ++++++++++++++++++++++++++++++++++++++++++
 doc/websupport.rst     |  9 ++++++
 4 files changed, 108 insertions(+)
 create mode 100644 doc/web/api.rst
 create mode 100644 doc/web/quickstart.rst
 create mode 100644 doc/websupport.rst

diff --git a/doc/contents.rst b/doc/contents.rst
index 079f93f26..1fb667112 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -17,6 +17,7 @@ Sphinx documentation contents
    theming
    templating
    extensions
+   websupport
 
    faq
    glossary
diff --git a/doc/web/api.rst b/doc/web/api.rst
new file mode 100644
index 000000000..a371fe3fc
--- /dev/null
+++ b/doc/web/api.rst
@@ -0,0 +1,26 @@
+.. _websupportapi:
+
+Web Support API
+===============
+
+.. module:: sphinx.websupport.api
+.. class:: WebSupport
+
+   The :class:`WebSupport` class provides a central interface for 
+   working with :ref:`~sphinx.websupport.document.Document's.
+
+.. method:: init(srcdir='', outdir='')
+
+   Initialize attributes.
+
+.. method:: get_document(docname)
+
+   Retrieve the :class:`~sphinx.websupport.document.Document` object
+   corresponding to the *docname*.
+
+.. module:: sphinx.websupport.document
+.. class:: Document
+   
+   The :class:`Document` provides access to a single document. It
+   is not instantiated directly, but is returned by methods of the
+   :class:`~sphinx.websupport.api.WebSupport` object.
diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
new file mode 100644
index 000000000..0a7094bfd
--- /dev/null
+++ b/doc/web/quickstart.rst
@@ -0,0 +1,72 @@
+.. _websupportquickstart:
+
+Web Support Quick Start
+=======================
+
+To use the :ref:`websupportapi` in your application you must import
+the :class:`~sphinx.websupport.api.WebSupport` object::
+
+    from sphinx.websupport import support
+
+This provides a reference to a :class:`~sphinx.websupport.api.WebSupport`
+object. You will then need to provide some information about your 
+environment::
+
+    support.init(srcdir='/path/to/rst/sources/',
+                 outdir='/path/to/build/outdir')
+
+You only need to provide a srcdir if you are building documentation::
+
+    support.build()
+
+This will create the data the web support package needs and place
+it in *outdir*. You can then access 
+:class:`~sphinx.websupport.document.Document` objects by calling
+the get_document(docname) method. For example, to retrieve the "contents" 
+document, do this::
+
+    contents_doc = support.get_document('contents')
+
+A more useful example, in the form of a `Flask <http://flask.pocoo.org/>`_
+application is::
+
+    from flask import Flask, render_template
+    from sphinx.websupport import support
+
+    app = Flask(__name__)
+
+    support.init(outdir='/path/to/sphinx/data')
+    
+    @app.route('/docs/<path:docname>')
+    def doc(docname):
+        document = support.get_document(docname)
+        return render_template('doc.html', document=document)
+
+This simple application will return a 
+:class:`~sphinx.websupport.document.Document` object corresponding 
+to the *docname* variable. This object will have *title* attribute,
+as well as a list of HTML "slices". Each slice contains some HTML,
+and when joined they form the body of a Sphinx document. Each slice
+may or may not be commentable. If a slice is commentable, it will
+have an *id* attribute which is used to associate a comment with
+part of a document.
+
+In the previous example the doc.html template would look something 
+like this::
+
+    {% extends "base.html" %}
+
+    {% block title %}
+      {{ document.title }}
+    {% endblock %}
+
+    {% block body %}
+      {% for slice in document.slices -%}
+        {{ slice.html|safe }}
+        {% if slice.commentable -%}
+          <a href="#" onclick="alert('[ comment stub for <{{ slice.id }}> ]'); return false;">
+            comment
+          </a>
+        {%- endif %}
+      {%- endfor %}
+    {% endblock %}
diff --git a/doc/websupport.rst b/doc/websupport.rst
new file mode 100644
index 000000000..a78704606
--- /dev/null
+++ b/doc/websupport.rst
@@ -0,0 +1,9 @@
+.. _websupport:
+
+Sphinx Web Support
+==================
+
+.. toctree::
+
+   web/quickstart
+   web/api
\ No newline at end of file

From b1f39eac033517bbb5bc56f2d022d1eb298a466c Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Fri, 4 Jun 2010 16:46:06 -0500
Subject: [PATCH 010/127] updated CHANGES.jacobmason

---
 CHANGES.jacobmason | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/CHANGES.jacobmason b/CHANGES.jacobmason
index 42adc4270..fe7c57fbb 100644
--- a/CHANGES.jacobmason
+++ b/CHANGES.jacobmason
@@ -1,2 +1,6 @@
 May 30: Added files builders/websupport.py, writers/websupport.py,
-websupport/api.py, and websupport/document.api. Provides a rudimentary method of building websupport data, and rendering it as html.
\ No newline at end of file
+websupport/api.py, and websupport/document.api. Provides a rudimentary 
+method of building websupport data, and rendering it as html.
+
+May 31-June 4: Continued changing way web support data is represented
+and accessed.
\ No newline at end of file

From 8e8fd9ca98c7335fab76797c6428d1b8769b33b9 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Mon, 7 Jun 2010 16:09:19 -0500
Subject: [PATCH 011/127] Now serves static body.

---
 doc/web/api.rst               |  2 +-
 sphinx/builders/websupport.py | 25 -----------------------
 sphinx/locale/__init__.py     |  3 +++
 sphinx/writers/websupport.py  | 38 ++++++++++++++++-------------------
 4 files changed, 21 insertions(+), 47 deletions(-)

diff --git a/doc/web/api.rst b/doc/web/api.rst
index a371fe3fc..66e89af3e 100644
--- a/doc/web/api.rst
+++ b/doc/web/api.rst
@@ -7,7 +7,7 @@ Web Support API
 .. class:: WebSupport
 
    The :class:`WebSupport` class provides a central interface for 
-   working with :ref:`~sphinx.websupport.document.Document's.
+   working with :class:`~sphinx.websupport.document.Document`'s.
 
 .. method:: init(srcdir='', outdir='')
 
diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 48e895db5..8bc94174b 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -9,9 +9,6 @@
     :license: BSD, see LICENSE for details.
 """
 
-from os import path
-
-from sphinx.util.osutil import ensuredir, os_path
 from sphinx.builders.html import PickleHTMLBuilder
 from sphinx.writers.websupport import WebSupportTranslator
 
@@ -20,7 +17,6 @@ class WebSupportBuilder(PickleHTMLBuilder):
     Builds documents for the web support package.
     """
     name = 'websupport'
-    template_suffix = '.html'
     
     def init_translator_class(self):
         self.translator_class = WebSupportTranslator
@@ -30,26 +26,5 @@ class WebSupportBuilder(PickleHTMLBuilder):
         self.docname = docname
         PickleHTMLBuilder.write_doc(self, docname, doctree)
 
-    def handle_page(self, pagename, ctx, templatename='', **ignored):
-        # Mostly copied from PickleHTMLBuilder.
-        ctx['current_page_name'] = ctx['pagename'] = pagename
-        self.add_sidebars(pagename, ctx)
-
-        self.app.emit('html-page-context', pagename, ctx)
-
-        # Instead of pickling ctx as PickleHTMLBuilder does, we
-        # have created a Document object and pickle that.
-        document = self.docwriter.visitor.support_document
-        document.__dict__.update(ctx)
-
-        doc_filename = path.join(self.outdir,
-                                 os_path(pagename) + self.out_suffix)
-        ensuredir(path.dirname(doc_filename))
-        f = open(doc_filename, 'wb')
-        try:
-            self.implementation.dump(document, f)
-        finally:
-            f.close()
-
     def get_target_uri(self, docname, typ=None):
         return docname
diff --git a/sphinx/locale/__init__.py b/sphinx/locale/__init__.py
index badcca1cd..43e0942cd 100644
--- a/sphinx/locale/__init__.py
+++ b/sphinx/locale/__init__.py
@@ -32,6 +32,9 @@ class _TranslationProxy(UserString.UserString, object):
             return unicode(func)
         return object.__new__(cls)
 
+    def __getnewargs__(self):
+        return (self._func,) + self._args
+
     def __init__(self, func, *args):
         self._func = func
         self._args = args
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 6d255e64c..d99d7dc91 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -10,7 +10,6 @@
 """
 
 from sphinx.writers.html import HTMLTranslator
-from sphinx.websupport.document import Document
 
 class WebSupportTranslator(HTMLTranslator):
     """
@@ -23,7 +22,6 @@ class WebSupportTranslator(HTMLTranslator):
         self.init_support()
 
     def init_support(self):
-        self.support_document = Document()
         self.in_commentable = False
         self.current_id = 0
         
@@ -38,29 +36,27 @@ class WebSupportTranslator(HTMLTranslator):
             self.handle_depart_commentable(node)
 
     def handle_visit_commentable(self, node):
-        # If we are already recording a commentable slice we don't do
-        # anything. We can't handle nesting.
-        if not self.in_commentable:
-            self.support_document.add_slice(''.join(self.body))
-            node.commented = self.in_commentable = True
-            self.body = []
-        else:
+        # If this node is nested inside another commentable node this
+        # node will not be commented.
+        if self.in_commentable:
             node.commented = False
+        else:
+            node.commented = self.in_commentable = True
+            node.id = self.create_id(node)
+            # We will place the node in the HTML id attribute. If the node
+            # already has another id (for indexing purposes) put an empty
+            # span with the existing id directly before this node's HTML.
+            if node.attributes['ids']:
+                self.body.append('<span id="%s"></span>'
+                                 % node.attributes['ids'][0])
+            node.attributes['ids'] = [node.id]
+            node.attributes['classes'].append('spxcmt')
 
     def handle_depart_commentable(self, node):
         assert(self.in_commentable)
         if node.commented:
-            slice_id = '%s-%s' % (self.builder.docname, self.current_id)
-            self.current_id += 1
-
-            body = ''.join(self.body)
-            self.support_document.add_slice(body, slice_id, commentable=True)
-
             self.in_commentable = False
-            self.body = []
-
-    def depart_document(self, node):
-        assert(not self.in_commentable)
-        self.support_document.add_slice(''.join(self.body))
-                
 
+    def create_id(self, node):
+        self.current_id += 1
+        return '%s_%s' % (node.__class__.__name__, self.current_id)

From 51ea0cb2fe5f71f3674a6cea45ceacbe43a16e96 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Mon, 7 Jun 2010 18:19:40 -0500
Subject: [PATCH 012/127] removed document.py

---
 sphinx/websupport/document.py | 31 -------------------------------
 1 file changed, 31 deletions(-)
 delete mode 100644 sphinx/websupport/document.py

diff --git a/sphinx/websupport/document.py b/sphinx/websupport/document.py
deleted file mode 100644
index 16a60934b..000000000
--- a/sphinx/websupport/document.py
+++ /dev/null
@@ -1,31 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-    sphinx.websupport.document
-    ~~~~~~~~~~~~~~~~~~~~
-
-    Contains a Document class for working with Sphinx documents.
-
-    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
-
-from os import path
-
-from jinja2 import Template
-from docutils import nodes
-from sphinx import addnodes
-
-class Document(object):
-    """A single Document such as 'index'."""
-    def __init__(self):
-        self.slices = []
-
-    def add_slice(self, html, id=None, commentable=False):
-        slice = HTMLSlice(html, id, commentable)
-        self.slices.append(slice)
-
-class HTMLSlice(object):
-    def __init__(self, html, id, commentable):
-        self.html = html
-        self.id = id
-        self.commentable = commentable

From ed7c1ad43dd15c112c919e96a8474d9660ee90ae Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Tue, 15 Jun 2010 22:10:36 -0500
Subject: [PATCH 013/127] Don't add attributes to node.

---
 doc/websupport.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/websupport.rst b/doc/websupport.rst
index a78704606..2927f5a79 100644
--- a/doc/websupport.rst
+++ b/doc/websupport.rst
@@ -3,6 +3,10 @@
 Sphinx Web Support
 ==================
 
+Sphinx provides a way to easily integrate Sphinx documentation
+into your web application. To learn more read the 
+:ref:`websupportquickstart`.
+
 .. toctree::
 
    web/quickstart

From cd227483ea2f162ea0e62e42563400a7bab808c3 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Tue, 15 Jun 2010 22:15:10 -0500
Subject: [PATCH 014/127] Don't add attributes to node.

---
 sphinx/writers/websupport.py | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index d99d7dc91..4afc3ecbd 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -19,6 +19,7 @@ class WebSupportTranslator(HTMLTranslator):
 
     def __init__(self, builder, *args, **kwargs):
         HTMLTranslator.__init__(self, builder, *args, **kwargs)
+        self.comment_class = 'spxcmt'
         self.init_support()
 
     def init_support(self):
@@ -38,23 +39,21 @@ class WebSupportTranslator(HTMLTranslator):
     def handle_visit_commentable(self, node):
         # If this node is nested inside another commentable node this
         # node will not be commented.
-        if self.in_commentable:
-            node.commented = False
-        else:
-            node.commented = self.in_commentable = True
-            node.id = self.create_id(node)
+        if not self.in_commentable:
+            self.in_commentable = True
+            id = self.create_id(node)
             # We will place the node in the HTML id attribute. If the node
             # already has another id (for indexing purposes) put an empty
             # span with the existing id directly before this node's HTML.
             if node.attributes['ids']:
                 self.body.append('<span id="%s"></span>'
                                  % node.attributes['ids'][0])
-            node.attributes['ids'] = [node.id]
-            node.attributes['classes'].append('spxcmt')
+            node.attributes['ids'] = [id]
+            node.attributes['classes'].append(self.comment_class)
 
     def handle_depart_commentable(self, node):
         assert(self.in_commentable)
-        if node.commented:
+        if self.comment_class in node.attributes['classes']:
             self.in_commentable = False
 
     def create_id(self, node):

From 3613ce1a42848f237d7da6d65f02a667e40863d0 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Wed, 16 Jun 2010 08:33:33 -0500
Subject: [PATCH 015/127] updated documentation

---
 doc/web/api.rst        | 12 ++---------
 doc/web/quickstart.rst | 47 +++++++++++++++++++++++-------------------
 2 files changed, 28 insertions(+), 31 deletions(-)

diff --git a/doc/web/api.rst b/doc/web/api.rst
index 66e89af3e..65bf0c583 100644
--- a/doc/web/api.rst
+++ b/doc/web/api.rst
@@ -7,7 +7,7 @@ Web Support API
 .. class:: WebSupport
 
    The :class:`WebSupport` class provides a central interface for 
-   working with :class:`~sphinx.websupport.document.Document`'s.
+   working Sphinx documentation.
 
 .. method:: init(srcdir='', outdir='')
 
@@ -15,12 +15,4 @@ Web Support API
 
 .. method:: get_document(docname)
 
-   Retrieve the :class:`~sphinx.websupport.document.Document` object
-   corresponding to the *docname*.
-
-.. module:: sphinx.websupport.document
-.. class:: Document
-   
-   The :class:`Document` provides access to a single document. It
-   is not instantiated directly, but is returned by methods of the
-   :class:`~sphinx.websupport.api.WebSupport` object.
+   Retrieve the context dictionary corresponding to the *docname*.
diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
index 0a7094bfd..94dfb576a 100644
--- a/doc/web/quickstart.rst
+++ b/doc/web/quickstart.rst
@@ -20,13 +20,15 @@ You only need to provide a srcdir if you are building documentation::
     support.build()
 
 This will create the data the web support package needs and place
-it in *outdir*. You can then access 
-:class:`~sphinx.websupport.document.Document` objects by calling
-the get_document(docname) method. For example, to retrieve the "contents" 
+it in *outdir*. You can then access this data by calling the 
+get_document(docname) method. For example, to retrieve the "contents" 
 document, do this::
 
     contents_doc = support.get_document('contents')
 
+This will return a dictionary containing the context you need to render
+a document.
+
 A more useful example, in the form of a `Flask <http://flask.pocoo.org/>`_
 application is::
 
@@ -42,15 +44,6 @@ application is::
         document = support.get_document(docname)
         return render_template('doc.html', document=document)
 
-This simple application will return a 
-:class:`~sphinx.websupport.document.Document` object corresponding 
-to the *docname* variable. This object will have *title* attribute,
-as well as a list of HTML "slices". Each slice contains some HTML,
-and when joined they form the body of a Sphinx document. Each slice
-may or may not be commentable. If a slice is commentable, it will
-have an *id* attribute which is used to associate a comment with
-part of a document.
-
 In the previous example the doc.html template would look something 
 like this::
 
@@ -60,13 +53,25 @@ like this::
       {{ document.title }}
     {% endblock %}
 
-    {% block body %}
-      {% for slice in document.slices -%}
-        {{ slice.html|safe }}
-        {% if slice.commentable -%}
-          <a href="#" onclick="alert('[ comment stub for <{{ slice.id }}> ]'); return false;">
-            comment
-          </a>
-        {%- endif %}
-      {%- endfor %}
+    {% block extra_js %}
+      <script type="text/javascript" src="/static/jquery.js"></script>
+      <script type="text/javascript">
+        <!--
+        $(document).ready(function() {
+          $(".spxcmt").append(' <a href="#" class="sphinx_comment"><img src="/static/comment.png" /></a>');
+          $("a.sphinx_comment").click(function() {
+            id = $(this).parent().attr('id');
+            alert('[ comment stub ' + id + ' ]');
+            return false;
+          });
+        });
+        -->
+      </script>
+    {% endblock %}
+
+    {% block body %}
+      {{ document.body|safe }}
+    {% endblock %}
+
+    {% block sidebar %}
     {% endblock %}

From 95d95edacc09715b1e4834b9ae8b787832d7efcf Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Wed, 16 Jun 2010 08:41:43 -0500
Subject: [PATCH 016/127] fixed typo in docs

---
 doc/web/api.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/web/api.rst b/doc/web/api.rst
index 65bf0c583..13df6a40f 100644
--- a/doc/web/api.rst
+++ b/doc/web/api.rst
@@ -7,7 +7,7 @@ Web Support API
 .. class:: WebSupport
 
    The :class:`WebSupport` class provides a central interface for 
-   working Sphinx documentation.
+   working with Sphinx documentation.
 
 .. method:: init(srcdir='', outdir='')
 

From 00f841be2ab3bb44766a1cff18924f6e65a98207 Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Wed, 23 Jun 2010 14:37:07 -0500
Subject: [PATCH 017/127] Added relbar and sidebar to documents

---
 sphinx/builders/websupport.py | 67 ++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 8bc94174b..55b90e683 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -9,22 +9,81 @@
     :license: BSD, see LICENSE for details.
 """
 
-from sphinx.builders.html import PickleHTMLBuilder
+import cPickle as pickle
+from os import path
+
+from sphinx.util.osutil import os_path, relative_uri, ensuredir, copyfile
+from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.writers.websupport import WebSupportTranslator
 
-class WebSupportBuilder(PickleHTMLBuilder):
+class WebSupportBuilder(StandaloneHTMLBuilder):
     """
     Builds documents for the web support package.
     """
     name = 'websupport'
-    
+    out_suffix = '.fpickle'
+
     def init_translator_class(self):
         self.translator_class = WebSupportTranslator
         
     def write_doc(self, docname, doctree):
         # The translator needs the docname to generate ids.
         self.docname = docname
-        PickleHTMLBuilder.write_doc(self, docname, doctree)
+        StandaloneHTMLBuilder.write_doc(self, docname, doctree)
 
     def get_target_uri(self, docname, typ=None):
         return docname
+
+    def handle_page(self, pagename, addctx, templatename='page.html',
+                    outfilename=None, event_arg=None):
+        # This is mostly copied from StandaloneHTMLBuilder. However, instead
+        # of rendering the template and saving the html, create a context 
+        # dict and pickle it.
+        ctx = self.globalcontext.copy()
+        ctx['pagename'] = pagename
+
+        def pathto(otheruri, resource=False,
+                   baseuri=self.get_target_uri(pagename)):
+            if not resource:
+                otheruri = self.get_target_uri(otheruri)
+            uri = relative_uri(baseuri, otheruri) or '#'
+            return uri
+        ctx['pathto'] = pathto
+        ctx['hasdoc'] = lambda name: name in self.env.all_docs
+        ctx['encoding'] = encoding = self.config.html_output_encoding
+        ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw)
+        self.add_sidebars(pagename, ctx)
+        ctx.update(addctx)
+
+        self.app.emit('html-page-context', pagename, templatename,
+                      ctx, event_arg)
+
+        # Create a dict that will be pickled and used by webapps.
+        doc_ctx = {'body': ctx.get('body', '')}
+        # Partially render the html template to proved a more useful ctx.
+        template = self.templates.environment.get_template(templatename)
+        template_module = template.make_module(ctx)
+        if hasattr(template_module, 'sidebar'):
+            doc_ctx['sidebar'] = template_module.sidebar()
+        if hasattr(template_module, 'relbar'):
+            doc_ctx['relbar'] = template_module.relbar()
+
+        if not outfilename:
+            outfilename = path.join(self.outdir,
+                                    os_path(pagename) + self.out_suffix)
+
+        ensuredir(path.dirname(outfilename))
+        f = open(outfilename, 'wb')
+        try:
+            pickle.dump(doc_ctx, f, 2)
+        finally:
+            f.close()
+
+        # if there is a source file, copy the source file for the
+        # "show source" link
+        if ctx.get('sourcename'):
+            source_name = path.join(self.outdir, '_sources',
+                                    os_path(ctx['sourcename']))
+            ensuredir(path.dirname(source_name))
+            copyfile(self.env.doc2path(pagename), source_name)
+

From 8c4e5351702f5125e8ed9044bf2dcaa9b5485a0a Mon Sep 17 00:00:00 2001
From: jacob <jacob@panda>
Date: Thu, 24 Jun 2010 14:30:02 -0500
Subject: [PATCH 018/127] Added xapian search

---
 sphinx/builders/websupport.py            | 18 +++++-
 sphinx/themes/basic/searchresults.html   | 36 +++++++++++
 sphinx/websupport/api.py                 | 44 ++++++++++++--
 sphinx/websupport/search/__init__.py     | 36 +++++++++++
 sphinx/websupport/search/xapiansearch.py | 76 ++++++++++++++++++++++++
 5 files changed, 204 insertions(+), 6 deletions(-)
 create mode 100644 sphinx/themes/basic/searchresults.html
 create mode 100644 sphinx/websupport/search/__init__.py
 create mode 100644 sphinx/websupport/search/xapiansearch.py

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 55b90e683..8972c5479 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -23,12 +23,26 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     name = 'websupport'
     out_suffix = '.fpickle'
 
+    def init(self):
+        self.init_search()
+        StandaloneHTMLBuilder.init(self)
+
+    def init_search(self):
+        self.search = self.app.search
+        if self.search is not None:
+            self.search.create_index()
+
     def init_translator_class(self):
         self.translator_class = WebSupportTranslator
         
     def write_doc(self, docname, doctree):
         # The translator needs the docname to generate ids.
         self.docname = docname
+        # Index the page if search is enabled.
+        if self.search is not None:
+            doc_contents = doctree.astext()
+            title = doc_contents[:20]
+            self.search.add_document(docname, title, doc_contents) 
         StandaloneHTMLBuilder.write_doc(self, docname, doctree)
 
     def get_target_uri(self, docname, typ=None):
@@ -59,7 +73,8 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
                       ctx, event_arg)
 
         # Create a dict that will be pickled and used by webapps.
-        doc_ctx = {'body': ctx.get('body', '')}
+        doc_ctx = {'body': ctx.get('body', ''),
+                   'title': ctx.get('title', '')}
         # Partially render the html template to proved a more useful ctx.
         template = self.templates.environment.get_template(templatename)
         template_module = template.make_module(ctx)
@@ -86,4 +101,3 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
                                     os_path(ctx['sourcename']))
             ensuredir(path.dirname(source_name))
             copyfile(self.env.doc2path(pagename), source_name)
-
diff --git a/sphinx/themes/basic/searchresults.html b/sphinx/themes/basic/searchresults.html
new file mode 100644
index 000000000..0fec38dea
--- /dev/null
+++ b/sphinx/themes/basic/searchresults.html
@@ -0,0 +1,36 @@
+{#
+    basic/searchresults.html
+    ~~~~~~~~~~~~~~~~~
+
+    Template for the body of the search results page.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+<h1 id="search-documentation">Search</h1>
+<p>
+  From here you can search these documents. Enter your search
+  words into the box below and click "search".
+</p>
+<form action="" method="get">
+  <input type="text" name="q" value="" />
+  <input type="submit" value="search" />
+  <span id="search-progress" style="padding-left: 10px"></span>
+</form>
+{% if search_performed %}
+<h2>Search Results</h2>
+{% if not search_results %}
+<p>'Your search did not match any results.</p>
+{% endif %}
+{% endif %}
+<div id="search-results">
+  {% if search_results %}
+  <ul>
+    {% for href, caption, context in search_results %}
+    <li><a href="{{ href }}">{{ caption }}</a>
+      <div class="context">{{ context|e }}</div>
+    </li>
+    {% endfor %}
+  </ul>
+  {% endif %}
+</div>
diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index 0d2722d66..cc5f2f500 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -12,20 +12,47 @@
 import cPickle as pickle
 from os import path
 
+from jinja2 import Environment, FileSystemLoader
+
 from sphinx.application import Sphinx
+from sphinx.websupport.search import search_adapters
+
+class WebSupportApp(Sphinx):
+    def __init__(self, *args, **kwargs):
+        self.search = kwargs.pop('search', None)
+        Sphinx.__init__(self, *args, **kwargs)
 
 class WebSupport(object):
-    
-    def init(self, srcdir='', outdir=''):
+    def init(self, srcdir='', outdir='', search=None):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
+        self.init_templating()        
+        if search is not None:
+            self.init_search(search)
+        
+    def init_templating(self):
+        import sphinx
+        template_path = path.join(path.dirname(sphinx.__file__),
+                                  'themes', 'basic')
+        loader = FileSystemLoader(template_path)
+        self.template_env = Environment(loader=loader)
+
+    def init_search(self, search):
+        mod, cls = search_adapters[search]
+        search_class = getattr(__import__('sphinx.websupport.search.' + mod, 
+                                          None, None, [cls]), cls)
+        search_path = path.join(self.outdir, 'search')
+        self.search = search_class(search_path)
+        self.results_template = \
+            self.template_env.get_template('searchresults.html')
 
     def build(self, **kwargs):
         doctreedir = kwargs.pop('doctreedir', 
                                 path.join(self.outdir, 'doctrees'))
-        app = Sphinx(self.srcdir, self.srcdir,
-                     self.outdir, doctreedir, 'websupport')
+        app = WebSupportApp(self.srcdir, self.srcdir,
+                            self.outdir, doctreedir, 'websupport',
+                            search=self.search)
         app.build()
 
     def get_document(self, docname):
@@ -33,3 +60,12 @@ class WebSupport(object):
         f = open(infilename, 'rb')
         document = pickle.load(f)
         return document
+
+    def get_search_results(self, q):
+        results, results_found, results_displayed = self.search.query(q)
+        ctx = {'search_performed': True,
+               'search_results': results}
+        document = self.get_document('search')
+        document['body'] = self.results_template.render(ctx)
+        document['title'] = 'Search Results'
+        return document
diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
new file mode 100644
index 000000000..ae82005a9
--- /dev/null
+++ b/sphinx/websupport/search/__init__.py
@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.search
+    ~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Server side search support for the web support package.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import re
+
+class BaseSearch(object):
+    def create_index(self, path):
+        raise NotImplemented
+
+    def add_document(self, path, title, text):
+        raise NotImplemented
+
+    def query(self, q):
+        raise NotImplemented
+
+    def extract_context(self, text, query_string):
+        # From GSOC 2009
+        with_context_re = '([\W\w]{0,80})(%s)([\W\w]{0,80})' % (query_string)
+        try:
+            res = re.findall(with_context_re, text, re.I|re.U)[0]
+            return tuple((unicode(i, errors='ignore') for i in res))
+        except IndexError:
+            return '', '', ''
+
+search_adapters = {
+    'xapian': ('xapiansearch', 'XapianSearch'),
+    'whoosh': ('whooshsearch', 'WhooshSearch'),
+    }
diff --git a/sphinx/websupport/search/xapiansearch.py b/sphinx/websupport/search/xapiansearch.py
new file mode 100644
index 000000000..746a644d3
--- /dev/null
+++ b/sphinx/websupport/search/xapiansearch.py
@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.search.xapian
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Xapian search adapter.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from os import path
+
+import xapian
+
+from sphinx.util.osutil import ensuredir
+from sphinx.websupport.search import BaseSearch
+
+class XapianSearch(BaseSearch):
+    # Adapted from the GSOC 2009 webapp project.
+
+    # Xapian metadata constants
+    DOC_PATH = 0
+    DOC_TITLE = 1
+
+    def __init__(self, db_path):
+        self.db_path = db_path
+
+    def create_index(self):
+        ensuredir(self.db_path)
+        self.database = xapian.WritableDatabase(self.db_path, 
+                                                xapian.DB_CREATE_OR_OPEN)
+        self.indexer = xapian.TermGenerator()
+        stemmer = xapian.Stem("english")
+        self.indexer.set_stemmer(stemmer)
+       
+    def add_document(self, path, title, text):
+        self.database.begin_transaction()
+        doc = xapian.Document()
+        doc.set_data(text)
+        doc.add_value(self.DOC_PATH, path)
+        doc.add_value(self.DOC_TITLE, title)
+        self.indexer.set_document(doc)
+        self.indexer.index_text(text)
+        for word in text.split():
+            doc.add_posting(word, 1)
+        self.database.add_document(doc)
+        self.database.commit_transaction()
+
+    def query(self, q):
+        database = xapian.Database(self.db_path)
+        enquire = xapian.Enquire(database)
+        qp = xapian.QueryParser()
+        stemmer = xapian.Stem("english")
+        qp.set_stemmer(stemmer)
+        qp.set_database(database)
+        qp.set_stemming_strategy(xapian.QueryParser.STEM_SOME)
+        query = qp.parse_query(q)
+
+        # Find the top 100 results for the query.
+        enquire.set_query(query)
+        matches = enquire.get_mset(0, 100)
+
+        results_found = matches.get_matches_estimated()
+        results_displayed = matches.size()
+
+        results = []
+
+        for m in matches:
+            context = self.extract_context(m.document.get_data(), q)
+            results.append((m.document.get_value(self.DOC_PATH),
+                            m.document.get_value(self.DOC_TITLE),
+                            ''.join(context) ))
+
+        return results, results_found, results_displayed
+        

From 05c9c2842b28e55e49f0d1c00df7471f53b65885 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 25 Jun 2010 14:37:46 -0500
Subject: [PATCH 019/127] Fixed styling problems in search results.

---
 sphinx/themes/basic/searchresults.html | 4 ++--
 sphinx/websupport/api.py               | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/sphinx/themes/basic/searchresults.html b/sphinx/themes/basic/searchresults.html
index 0fec38dea..e7fc84f8f 100644
--- a/sphinx/themes/basic/searchresults.html
+++ b/sphinx/themes/basic/searchresults.html
@@ -25,9 +25,9 @@
 {% endif %}
 <div id="search-results">
   {% if search_results %}
-  <ul>
+  <ul class="search">
     {% for href, caption, context in search_results %}
-    <li><a href="{{ href }}">{{ caption }}</a>
+    <li><a href="{{ href }}?highlight={{ q }}">{{ caption }}</a>
       <div class="context">{{ context|e }}</div>
     </li>
     {% endfor %}
diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index cc5f2f500..90e548df8 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -64,7 +64,8 @@ class WebSupport(object):
     def get_search_results(self, q):
         results, results_found, results_displayed = self.search.query(q)
         ctx = {'search_performed': True,
-               'search_results': results}
+               'search_results': results,
+               'q': q}
         document = self.get_document('search')
         document['body'] = self.results_template.render(ctx)
         document['title'] = 'Search Results'

From 3babf6e968eac72c7ab4b7728fb796fd1d694057 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 25 Jun 2010 14:41:30 -0500
Subject: [PATCH 020/127] fixed search result titles and context

---
 sphinx/builders/websupport.py            | 25 ++++++++++-------------
 sphinx/websupport/search/__init__.py     | 26 ++++++++++++++++--------
 sphinx/websupport/search/xapiansearch.py |  5 ++++-
 3 files changed, 33 insertions(+), 23 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 8972c5479..19b084628 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -23,31 +23,25 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     name = 'websupport'
     out_suffix = '.fpickle'
 
-    def init(self):
-        self.init_search()
-        StandaloneHTMLBuilder.init(self)
-
-    def init_search(self):
-        self.search = self.app.search
-        if self.search is not None:
-            self.search.create_index()
-
     def init_translator_class(self):
         self.translator_class = WebSupportTranslator
         
     def write_doc(self, docname, doctree):
         # The translator needs the docname to generate ids.
         self.docname = docname
-        # Index the page if search is enabled.
-        if self.search is not None:
-            doc_contents = doctree.astext()
-            title = doc_contents[:20]
-            self.search.add_document(docname, title, doc_contents) 
         StandaloneHTMLBuilder.write_doc(self, docname, doctree)
 
     def get_target_uri(self, docname, typ=None):
         return docname
 
+    def load_indexer(self, docnames):
+        keep = set(self.env.all_docs) - set(docnames)
+        self.indexer = self.app.search
+        if self.indexer is not None:
+            self.indexer.create_index()
+        # delete all entries for files that will be rebuilt
+        self.indexer.prune(keep)
+
     def handle_page(self, pagename, addctx, templatename='page.html',
                     outfilename=None, event_arg=None):
         # This is mostly copied from StandaloneHTMLBuilder. However, instead
@@ -101,3 +95,6 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
                                     os_path(ctx['sourcename']))
             ensuredir(path.dirname(source_name))
             copyfile(self.env.doc2path(pagename), source_name)
+
+    def dump_search_index(self):
+        pass
diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index ae82005a9..189016094 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -15,21 +15,31 @@ class BaseSearch(object):
     def create_index(self, path):
         raise NotImplemented
 
+    def feed(self, pagename, title, doctree):
+        self.add_document(pagename, title, doctree.astext())
+
     def add_document(self, path, title, text):
         raise NotImplemented
 
+    def prune(self, keep):
+        raise NotImplemented
+
     def query(self, q):
+        self.context_re = re.compile(q, re.I)
+        return self.handle_query(q)
+
+    def handle_query(self, q):
         raise NotImplemented
 
     def extract_context(self, text, query_string):
-        # From GSOC 2009
-        with_context_re = '([\W\w]{0,80})(%s)([\W\w]{0,80})' % (query_string)
-        try:
-            res = re.findall(with_context_re, text, re.I|re.U)[0]
-            return tuple((unicode(i, errors='ignore') for i in res))
-        except IndexError:
-            return '', '', ''
-
+        res = self.context_re.search(text)
+        start = max(res.start() - 120, 0)
+        end = start + 240
+        context = ['...' if start > 0 else '',
+                   text[start:end],
+                   '...' if end < len(text) else '']
+        return ''.join(context)
+    
 search_adapters = {
     'xapian': ('xapiansearch', 'XapianSearch'),
     'whoosh': ('whooshsearch', 'WhooshSearch'),
diff --git a/sphinx/websupport/search/xapiansearch.py b/sphinx/websupport/search/xapiansearch.py
index 746a644d3..176d63e12 100644
--- a/sphinx/websupport/search/xapiansearch.py
+++ b/sphinx/websupport/search/xapiansearch.py
@@ -47,7 +47,10 @@ class XapianSearch(BaseSearch):
         self.database.add_document(doc)
         self.database.commit_transaction()
 
-    def query(self, q):
+    def prune(self, keep):
+        pass
+
+    def handle_query(self, q):
         database = xapian.Database(self.db_path)
         enquire = xapian.Enquire(database)
         qp = xapian.QueryParser()

From d9b07f4c7d54a3d93400d59c993eb7f9b77660be Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 25 Jun 2010 18:38:40 -0500
Subject: [PATCH 021/127] delete replaced documents in xapian when docs are
 rebuilt

---
 sphinx/builders/websupport.py            |  7 ++-----
 sphinx/websupport/search/__init__.py     | 14 ++++++++------
 sphinx/websupport/search/xapiansearch.py | 17 +++++++++++------
 3 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 19b084628..cd14fb9ef 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -37,10 +37,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     def load_indexer(self, docnames):
         keep = set(self.env.all_docs) - set(docnames)
         self.indexer = self.app.search
-        if self.indexer is not None:
-            self.indexer.create_index()
-        # delete all entries for files that will be rebuilt
-        self.indexer.prune(keep)
+        self.indexer.init_indexing()
 
     def handle_page(self, pagename, addctx, templatename='page.html',
                     outfilename=None, event_arg=None):
@@ -97,4 +94,4 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
             copyfile(self.env.doc2path(pagename), source_name)
 
     def dump_search_index(self):
-        pass
+        self.indexer.finish_indexing()
diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index 189016094..b9fb55162 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -12,8 +12,11 @@
 import re
 
 class BaseSearch(object):
-    def create_index(self, path):
-        raise NotImplemented
+    def init_indexing(self):
+        pass
+
+    def finish_indexing(self):
+        pass
 
     def feed(self, pagename, title, doctree):
         self.add_document(pagename, title, doctree.astext())
@@ -21,9 +24,6 @@ class BaseSearch(object):
     def add_document(self, path, title, text):
         raise NotImplemented
 
-    def prune(self, keep):
-        raise NotImplemented
-
     def query(self, q):
         self.context_re = re.compile(q, re.I)
         return self.handle_query(q)
@@ -33,12 +33,14 @@ class BaseSearch(object):
 
     def extract_context(self, text, query_string):
         res = self.context_re.search(text)
+        if res is None:
+            return ''
         start = max(res.start() - 120, 0)
         end = start + 240
         context = ['...' if start > 0 else '',
                    text[start:end],
                    '...' if end < len(text) else '']
-        return ''.join(context)
+        return unicode(''.join(context), errors='ignore')
     
 search_adapters = {
     'xapian': ('xapiansearch', 'XapianSearch'),
diff --git a/sphinx/websupport/search/xapiansearch.py b/sphinx/websupport/search/xapiansearch.py
index 176d63e12..de8d8bb3d 100644
--- a/sphinx/websupport/search/xapiansearch.py
+++ b/sphinx/websupport/search/xapiansearch.py
@@ -26,30 +26,37 @@ class XapianSearch(BaseSearch):
     def __init__(self, db_path):
         self.db_path = db_path
 
-    def create_index(self):
+    def init_indexing(self):
         ensuredir(self.db_path)
         self.database = xapian.WritableDatabase(self.db_path, 
                                                 xapian.DB_CREATE_OR_OPEN)
         self.indexer = xapian.TermGenerator()
         stemmer = xapian.Stem("english")
         self.indexer.set_stemmer(stemmer)
+
+    def finish_indexing(self):
+        # Ensure the db lock is removed.
+        del self.database
        
     def add_document(self, path, title, text):
         self.database.begin_transaction()
+        # sphinx_page_path is used to easily retrieve documents by path.
+        sphinx_page_path = '"sphinxpagepath%s"' % path.replace('/', '_')
+        # Delete the old document if it exists.
+        self.database.delete_document(sphinx_page_path)
+
         doc = xapian.Document()
         doc.set_data(text)
         doc.add_value(self.DOC_PATH, path)
         doc.add_value(self.DOC_TITLE, title)
         self.indexer.set_document(doc)
         self.indexer.index_text(text)
+        doc.add_term(sphinx_page_path)
         for word in text.split():
             doc.add_posting(word, 1)
         self.database.add_document(doc)
         self.database.commit_transaction()
 
-    def prune(self, keep):
-        pass
-
     def handle_query(self, q):
         database = xapian.Database(self.db_path)
         enquire = xapian.Enquire(database)
@@ -63,7 +70,6 @@ class XapianSearch(BaseSearch):
         # Find the top 100 results for the query.
         enquire.set_query(query)
         matches = enquire.get_mset(0, 100)
-
         results_found = matches.get_matches_estimated()
         results_displayed = matches.size()
 
@@ -76,4 +82,3 @@ class XapianSearch(BaseSearch):
                             ''.join(context) ))
 
         return results, results_found, results_displayed
-        

From f83ff52ede328a50e0b980d4d07d5b5188e038e0 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 26 Jun 2010 13:40:39 -0500
Subject: [PATCH 022/127] added whoosh search adapter

---
 sphinx/builders/websupport.py            |  3 +-
 sphinx/websupport/search/__init__.py     | 14 +++---
 sphinx/websupport/search/whooshsearch.py | 56 ++++++++++++++++++++++++
 sphinx/websupport/search/xapiansearch.py |  6 +--
 4 files changed, 69 insertions(+), 10 deletions(-)
 create mode 100644 sphinx/websupport/search/whooshsearch.py

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index cd14fb9ef..ddf525c4b 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -35,9 +35,8 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
         return docname
 
     def load_indexer(self, docnames):
-        keep = set(self.env.all_docs) - set(docnames)
         self.indexer = self.app.search
-        self.indexer.init_indexing()
+        self.indexer.init_indexing(changed=docnames)
 
     def handle_page(self, pagename, addctx, templatename='page.html',
                     outfilename=None, event_arg=None):
diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index b9fb55162..e7164205d 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -12,7 +12,7 @@
 import re
 
 class BaseSearch(object):
-    def init_indexing(self):
+    def init_indexing(self, changed=[]):
         pass
 
     def finish_indexing(self):
@@ -37,10 +37,14 @@ class BaseSearch(object):
             return ''
         start = max(res.start() - 120, 0)
         end = start + 240
-        context = ['...' if start > 0 else '',
-                   text[start:end],
-                   '...' if end < len(text) else '']
-        return unicode(''.join(context), errors='ignore')
+        context = ''.join(['...' if start > 0 else '',
+                           text[start:end],
+                           '...' if end < len(text) else ''])
+        
+        try:
+            return unicode(context, errors='ignore')
+        except TypeError:
+            return context
     
 search_adapters = {
     'xapian': ('xapiansearch', 'XapianSearch'),
diff --git a/sphinx/websupport/search/whooshsearch.py b/sphinx/websupport/search/whooshsearch.py
new file mode 100644
index 000000000..991d42326
--- /dev/null
+++ b/sphinx/websupport/search/whooshsearch.py
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.search.whooshsearch
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Whoosh search adapter.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from whoosh import index
+from whoosh.fields import Schema, ID, TEXT, STORED
+from whoosh.analysis import StemmingAnalyzer
+from whoosh import highlight
+
+from sphinx.util.osutil import ensuredir
+from sphinx.websupport.search import BaseSearch
+
+class WhooshSearch(BaseSearch):
+    schema = Schema(path=ID(stored=True, unique=True),
+                    title=TEXT(field_boost=2.0, stored=True),
+                    text=TEXT(analyzer=StemmingAnalyzer(), stored=True))
+
+    def __init__(self, db_path):
+        ensuredir(db_path)
+        if index.exists_in(db_path):
+            self.index = index.open_dir(db_path)
+        else:
+            self.index = index.create_in(db_path, schema=self.schema)
+        self.searcher = self.index.searcher()
+
+    def init_indexing(self, changed=[]):
+        for changed_path in changed:
+            self.index.delete_by_term('path', changed_path)
+        self.writer = self.index.writer()
+
+    def finish_indexing(self):
+        self.writer.commit()
+       
+    def add_document(self, path, title, text):
+        self.writer.add_document(path=unicode(path),
+                                 title=title, 
+                                 text=text)
+
+    def handle_query(self, q):
+        res = self.searcher.find('text', q)
+        results = []
+        for result in res:
+            context = self.extract_context(result['text'], q)
+            
+            results.append((result['path'],
+                            result.get('title', ''),
+                            context))
+        
+        return results, len(res), res.scored_length()
diff --git a/sphinx/websupport/search/xapiansearch.py b/sphinx/websupport/search/xapiansearch.py
index de8d8bb3d..f8dbecd9c 100644
--- a/sphinx/websupport/search/xapiansearch.py
+++ b/sphinx/websupport/search/xapiansearch.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx.websupport.search.xapian
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    sphinx.websupport.search.xapiansearch
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
     Xapian search adapter.
 
@@ -26,7 +26,7 @@ class XapianSearch(BaseSearch):
     def __init__(self, db_path):
         self.db_path = db_path
 
-    def init_indexing(self):
+    def init_indexing(self, changed=[]):
         ensuredir(self.db_path)
         self.database = xapian.WritableDatabase(self.db_path, 
                                                 xapian.DB_CREATE_OR_OPEN)

From 9e569d650a85bb819c4d5b2a125d1d120d84eab9 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 26 Jun 2010 14:49:30 -0500
Subject: [PATCH 023/127] updated documentation

---
 doc/web/api.rst        |  4 ++++
 doc/web/quickstart.rst | 53 ++++++++++++++++++++++++++++++++++++++----
 2 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/doc/web/api.rst b/doc/web/api.rst
index 13df6a40f..ef8e47088 100644
--- a/doc/web/api.rst
+++ b/doc/web/api.rst
@@ -13,6 +13,10 @@ Web Support API
 
    Initialize attributes.
 
+.. method:: build()
+
+   Build the data used by the web support package.
+
 .. method:: get_document(docname)
 
    Retrieve the context dictionary corresponding to the *docname*.
diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
index 94dfb576a..d519323eb 100644
--- a/doc/web/quickstart.rst
+++ b/doc/web/quickstart.rst
@@ -3,6 +3,9 @@
 Web Support Quick Start
 =======================
 
+Getting Started
+~~~~~~~~~~~~~~~
+
 To use the :ref:`websupportapi` in your application you must import
 the :class:`~sphinx.websupport.api.WebSupport` object::
 
@@ -13,22 +16,48 @@ object. You will then need to provide some information about your
 environment::
 
     support.init(srcdir='/path/to/rst/sources/',
-                 outdir='/path/to/build/outdir')
+                 outdir='/path/to/build/outdir',
+		 search='xapian')
 
-You only need to provide a srcdir if you are building documentation::
+Note: You only need to provide a srcdir if you are building documentation.
+
+Building Documentation Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to use the web support package in a webapp, you will need to
+build the data it uses. This data includes document data used to display
+documentation and search indexes. To build this data, call the build method::
 
     support.build()
 
 This will create the data the web support package needs and place
-it in *outdir*. You can then access this data by calling the 
-get_document(docname) method. For example, to retrieve the "contents" 
-document, do this::
+it in *outdir*. 
+
+Accessing Document Data
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To access document data, call the get_document(docname) method. For example, 
+to retrieve the "contents" document, do this::
 
     contents_doc = support.get_document('contents')
 
 This will return a dictionary containing the context you need to render
 a document.
 
+Performing Searches
+~~~~~~~~~~~~~~~~~~~
+
+To perform a search, call the get_search_results(q) method, with *q* being
+the string to be searched for::
+
+    q = request.GET['q']
+    search_doc = support.get_search_results(q)
+
+This will return a dictionary in the same format as get_document() returns.
+
+Full Example
+~~~~~~~~~~~~
+
 A more useful example, in the form of a `Flask <http://flask.pocoo.org/>`_
 application is::
 
@@ -44,6 +73,11 @@ application is::
         document = support.get_document(docname)
         return render_template('doc.html', document=document)
 
+    @app.route('/docs/search')
+    def search():
+        document = support.get_search_results(request.args.get('q', ''))
+	return render_template('doc.html', document=document)
+
 In the previous example the doc.html template would look something 
 like this::
 
@@ -69,9 +103,18 @@ like this::
       </script>
     {% endblock %}
 
+    {% block relbar %}
+      {{ document.relbar|safe }}
+    {% endblock %}
+
     {% block body %}
       {{ document.body|safe }}
     {% endblock %}
 
     {% block sidebar %}
+      {{ document.sidebar|safe }}
     {% endblock %}
+
+    {% block relbar %}
+      {{ document.relbar|safe }}
+    {% endblock %}
\ No newline at end of file

From c4e5947f872948db77a6ffd1f1ad9935ad6b5b2e Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 28 Jun 2010 18:39:10 -0500
Subject: [PATCH 024/127] Api user instantiates WebSupport directly

---
 sphinx/websupport/__init__.py | 2 --
 sphinx/websupport/api.py      | 6 +++---
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 36c2dcc91..d23e80a7a 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -10,5 +10,3 @@
 """
 
 from sphinx.websupport.api import WebSupport
-
-support = WebSupport()
diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index 90e548df8..37f590971 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """
     sphinx.websupport.api
-    ~~~~~~~~~~~~~~~~~~~~
+    ~~~~~~~~~~~~~~~~~~~~~
 
     All API functions.
 
@@ -23,14 +23,14 @@ class WebSupportApp(Sphinx):
         Sphinx.__init__(self, *args, **kwargs)
 
 class WebSupport(object):
-    def init(self, srcdir='', outdir='', search=None):
+    def __init__(self, srcdir='', outdir='', search=None):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
         self.init_templating()        
         if search is not None:
             self.init_search(search)
-        
+
     def init_templating(self):
         import sphinx
         template_path = path.join(path.dirname(sphinx.__file__),

From ac262bb012458987adcb25941c845578232bd2ca Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 29 Jun 2010 10:39:49 -0500
Subject: [PATCH 025/127] Split q for context_re

---
 sphinx/websupport/search/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index e7164205d..b4bf73868 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -25,7 +25,7 @@ class BaseSearch(object):
         raise NotImplemented
 
     def query(self, q):
-        self.context_re = re.compile(q, re.I)
+        self.context_re = re.compile('|'.join(q.split()), re.I)
         return self.handle_query(q)
 
     def handle_query(self, q):

From 03056a8a31062034edb88521cafb2fa66238076f Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 8 Jul 2010 21:35:19 -0500
Subject: [PATCH 026/127] Basic comment system.

---
 sphinx/builders/websupport.py          |   2 +-
 sphinx/websupport/api.py               |  37 ++++++++-
 sphinx/websupport/comments/__init__.py | 106 +++++++++++++++++++++++++
 sphinx/websupport/comments/db.py       |  53 +++++++++++++
 sphinx/writers/websupport.py           |  16 ++--
 5 files changed, 204 insertions(+), 10 deletions(-)
 create mode 100644 sphinx/websupport/comments/__init__.py
 create mode 100644 sphinx/websupport/comments/db.py

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index ddf525c4b..e2caeccd1 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -28,7 +28,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
         
     def write_doc(self, docname, doctree):
         # The translator needs the docname to generate ids.
-        self.docname = docname
+        self.cur_docname = docname
         StandaloneHTMLBuilder.write_doc(self, docname, doctree)
 
     def get_target_uri(self, docname, typ=None):
diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index 37f590971..b8274f52c 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -11,26 +11,46 @@
 
 import cPickle as pickle
 from os import path
+from datetime import datetime
 
 from jinja2 import Environment, FileSystemLoader
 
 from sphinx.application import Sphinx
+from sphinx.util.osutil import ensuredir
 from sphinx.websupport.search import search_adapters
+from sphinx.websupport import comments as sphinxcomments
 
 class WebSupportApp(Sphinx):
     def __init__(self, *args, **kwargs):
         self.search = kwargs.pop('search', None)
+        self.comments = kwargs.pop('comments', None)
         Sphinx.__init__(self, *args, **kwargs)
 
 class WebSupport(object):
-    def __init__(self, srcdir='', outdir='', search=None):
+    def __init__(self, srcdir='', outdir='', search=None,
+                 comments=None):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
-        self.init_templating()        
+        self.init_templating()
         if search is not None:
             self.init_search(search)
 
+        self.init_comments(comments)
+    
+    def init_comments(self, comments):
+        if isinstance(comments, sphinxcomments.CommentBackend):
+            self.comments = comments
+        elif comments is not None:
+            # If a CommentBackend isn't provided, use the default
+            # SQLAlchemy backend with an SQLite db.
+            from sphinx.websupport.comments import SQLAlchemyComments
+            from sqlalchemy import create_engine
+            db_path = path.join(self.outdir, 'comments', 'comments.db')
+            ensuredir(path.dirname(db_path))
+            engine = create_engine('sqlite:///%s' % db_path)
+            self.comments = SQLAlchemyComments(engine)
+        
     def init_templating(self):
         import sphinx
         template_path = path.join(path.dirname(sphinx.__file__),
@@ -52,8 +72,11 @@ class WebSupport(object):
                                 path.join(self.outdir, 'doctrees'))
         app = WebSupportApp(self.srcdir, self.srcdir,
                             self.outdir, doctreedir, 'websupport',
-                            search=self.search)
+                            search=self.search,
+                            comments=self.comments)
+        self.comments.pre_build()
         app.build()
+        self.comments.post_build()
 
     def get_document(self, docname):
         infilename = path.join(self.outdir, docname + '.fpickle')
@@ -70,3 +93,11 @@ class WebSupport(object):
         document['body'] = self.results_template.render(ctx)
         document['title'] = 'Search Results'
         return document
+
+    def get_comments(self, node_id):
+        return self.comments.get_comments(node_id)
+
+    def add_comment(self, parent_id, text, displayed=True, user_id=None,
+                    rating=0, time=None):
+        return self.comments.add_comment(parent_id, text, displayed, user_id,
+                                         rating, time)
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
new file mode 100644
index 000000000..1876d4343
--- /dev/null
+++ b/sphinx/websupport/comments/__init__.py
@@ -0,0 +1,106 @@
+from datetime import datetime
+
+from sqlalchemy.orm import sessionmaker
+
+from sphinx.websupport.comments.db import Base, Node, Comment
+
+Session = sessionmaker()
+
+class CommentBackend(object):
+    def pre_build(self):
+        pass
+
+    def add_node(self, document, line, source, treeloc):
+        raise NotImplemented
+    
+    def post_build(self):
+        pass
+
+    def add_comment(self, parent_id, text, displayed, user_id, rating, time):
+        raise NotImplemented
+
+    def get_comments(self, parent_id):
+        raise NotImplemented
+
+
+class SQLAlchemyComments(CommentBackend):
+    def __init__(self, engine):
+        self.engine = engine
+        Base.metadata.bind = engine
+        Base.metadata.create_all()
+        Session.configure(bind=engine)
+        self.session = Session()
+
+    def add_node(self, document, line, source, treeloc):
+        node = Node(document, line, source, treeloc)
+        self.session.add(node)
+        return node.id
+
+    def post_build(self):
+        self.session.commit()
+
+    def add_comment(self, parent_id, text, displayed, user_id, rating, time):
+        time = time or datetime.now()
+
+        id = parent_id[1:]
+        if parent_id[0] == 's':
+            node = self.session.query(Node).filter(Node.id == id).first()
+            comment = Comment(text, displayed, user_id, rating, 
+                              time, node=node)
+        elif parent_id[0] == 'c':
+            parent = self.session.query(Comment).filter(Comment.id == id).first()
+            comment = Comment(text, displayed, user_id, rating, 
+                              time, parent=parent)
+            
+        self.session.add(comment)
+        self.session.commit()
+        return self.serializable(comment)
+        
+    def get_comments(self, parent_id):
+        parent_id = parent_id[1:]
+        node = self.session.query(Node).filter(Node.id == parent_id).first()
+        comments = []
+        for comment in node.comments:
+            comments.append(self.serializable(comment))
+
+        return comments
+
+    def serializable(self, comment):
+        time = {'year': comment.time.year,
+                'month': comment.time.month,
+                'day': comment.time.day,
+                'hour': comment.time.hour,
+                'minute': comment.time.minute,
+                'second': comment.time.second,
+                'iso': comment.time.isoformat(),
+                'delta': self.pretty_delta(comment)}
+
+        return {'text': comment.text,
+                'user_id': comment.user_id,
+                'id': comment.id,
+                'rating': self.pretty_rating(comment),
+                'time': time,
+                'node': comment.node.id if comment.node else None,
+                'parent': comment.parent.id if comment.parent else None,
+                'children': [self.serializable(child) 
+                             for child in comment.children]}
+
+    def pretty_rating(self, comment):
+        if comment.rating == 1:
+            return '%s point' % comment.rating
+        else:
+            return '%s points' % comment.rating
+
+    def pretty_delta(self, comment):
+        delta = datetime.now() - comment.time
+        days = delta.days
+        seconds = delta.seconds
+        hours = seconds / 3600
+        minutes = seconds / 60
+
+        if days == 0:
+            dt = (minutes, 'minute') if hours == 0 else (hours, 'hour')
+        else:
+            dt = (days, 'day')
+
+        return '%s %s ago' % dt if dt[0] == 1 else '%s %ss ago' % dt
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
new file mode 100644
index 000000000..ff731a9f1
--- /dev/null
+++ b/sphinx/websupport/comments/db.py
@@ -0,0 +1,53 @@
+from sqlalchemy import Column, Integer, Text, String, Boolean, ForeignKey,\
+DateTime
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import relation
+
+Base = declarative_base()
+
+db_prefix = 'sphinx_'
+
+class Node(Base):
+    """Data about a Node in a doctree."""
+    __tablename__ = db_prefix + 'nodes'
+    
+    id = Column(Integer, primary_key=True)
+    document = Column(String(256), nullable=False)
+    line = Column(Integer)
+    source = Column(Text, nullable=False)
+    treeloc = Column(String(32), nullable=False)
+    
+    def __init__(self, document, line, source, treeloc):
+        self.document = document
+        self.line = line
+        self.source = source
+        self.treeloc = treeloc
+
+    def __repr__(self):
+        return '<Node %s#%s>' % (document, treeloc)
+
+class Comment(Base):
+    __tablename__ = db_prefix + 'comments'
+
+    id = Column(Integer, primary_key=True)
+    rating = Column(Integer, nullable=False)
+    time = Column(DateTime, nullable=False)
+    text = Column(Text, nullable=False)
+    displayed = Column(Boolean, index=True, default=False)
+    user_id = Column(String(50), nullable=True)
+
+    node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
+    node = relation(Node, backref='comments')
+
+    parent_id = Column(Integer, ForeignKey(db_prefix + 'comments.id'))
+    parent = relation('Comment', backref='children', remote_side=[id])
+
+    def __init__(self, text, displayed, user_id, rating, time, 
+                 node=None, parent=None):
+        self.text = text
+        self.displayed = displayed
+        self.user_id = user_id
+        self.rating = rating
+        self.time = time
+        self.node = node
+        self.parent = parent
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 4afc3ecbd..18c0807d6 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -41,14 +41,14 @@ class WebSupportTranslator(HTMLTranslator):
         # node will not be commented.
         if not self.in_commentable:
             self.in_commentable = True
-            id = self.create_id(node)
+            node_id = self.add_db_node(node)
             # We will place the node in the HTML id attribute. If the node
-            # already has another id (for indexing purposes) put an empty
+            # already has an id (for indexing purposes) put an empty
             # span with the existing id directly before this node's HTML.
             if node.attributes['ids']:
                 self.body.append('<span id="%s"></span>'
                                  % node.attributes['ids'][0])
-            node.attributes['ids'] = [id]
+            node.attributes['ids'] = ['s%s' % node_id]
             node.attributes['classes'].append(self.comment_class)
 
     def handle_depart_commentable(self, node):
@@ -56,6 +56,10 @@ class WebSupportTranslator(HTMLTranslator):
         if self.comment_class in node.attributes['classes']:
             self.in_commentable = False
 
-    def create_id(self, node):
-        self.current_id += 1
-        return '%s_%s' % (node.__class__.__name__, self.current_id)
+    def add_db_node(self, node):
+        comments = self.builder.app.comments
+        db_node_id = comments.add_node(document=self.builder.cur_docname,
+                                       line=node.line,
+                                       source=node.rawsource,
+                                       treeloc='???')
+        return db_node_id

From 0b1fe951c1e8f211edbf9d0e32b57bc939c56030 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 8 Jul 2010 21:51:47 -0500
Subject: [PATCH 027/127] Track node pks without committing each node
 individually

---
 sphinx/websupport/comments/__init__.py | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 1876d4343..eeb17f5e2 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -31,10 +31,18 @@ class SQLAlchemyComments(CommentBackend):
         Session.configure(bind=engine)
         self.session = Session()
 
+    def pre_build(self):
+        self.current_pk = None
+
     def add_node(self, document, line, source, treeloc):
         node = Node(document, line, source, treeloc)
         self.session.add(node)
-        return node.id
+        if self.current_pk is None:
+            self.session.commit()
+            self.current_pk = node.id
+        else:
+            self.current_pk += 1
+        return self.current_pk
 
     def post_build(self):
         self.session.commit()

From 940c48aabc3b73776883c949b354541b6210f9ce Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 9 Jul 2010 14:32:10 -0500
Subject: [PATCH 028/127] Add way to get user information from id

---
 sphinx/websupport/api.py               | 8 ++++----
 sphinx/websupport/comments/__init__.py | 5 +++--
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index b8274f52c..c5948306e 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -28,7 +28,7 @@ class WebSupportApp(Sphinx):
 
 class WebSupport(object):
     def __init__(self, srcdir='', outdir='', search=None,
-                 comments=None):
+                 comments=None, get_user=None):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
@@ -36,9 +36,9 @@ class WebSupport(object):
         if search is not None:
             self.init_search(search)
 
-        self.init_comments(comments)
+        self.init_comments(comments, get_user)
     
-    def init_comments(self, comments):
+    def init_comments(self, comments, get_user):
         if isinstance(comments, sphinxcomments.CommentBackend):
             self.comments = comments
         elif comments is not None:
@@ -49,7 +49,7 @@ class WebSupport(object):
             db_path = path.join(self.outdir, 'comments', 'comments.db')
             ensuredir(path.dirname(db_path))
             engine = create_engine('sqlite:///%s' % db_path)
-            self.comments = SQLAlchemyComments(engine)
+            self.comments = SQLAlchemyComments(engine, get_user)
         
     def init_templating(self):
         import sphinx
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index eeb17f5e2..8967bef61 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -24,7 +24,8 @@ class CommentBackend(object):
 
 
 class SQLAlchemyComments(CommentBackend):
-    def __init__(self, engine):
+    def __init__(self, engine, get_user):
+        self.get_user = get_user
         self.engine = engine
         Base.metadata.bind = engine
         Base.metadata.create_all()
@@ -84,7 +85,7 @@ class SQLAlchemyComments(CommentBackend):
                 'delta': self.pretty_delta(comment)}
 
         return {'text': comment.text,
-                'user_id': comment.user_id,
+                'user': self.get_user(comment.user_id),
                 'id': comment.id,
                 'rating': self.pretty_rating(comment),
                 'time': time,

From d08dae898a9df196bcb02855269263917e3312d0 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 10 Jul 2010 12:27:45 -0500
Subject: [PATCH 029/127] Comment Voting

---
 sphinx/websupport/api.py               | 22 ++++++----
 sphinx/websupport/comments/__init__.py | 59 +++++++++++++++++---------
 sphinx/websupport/comments/db.py       | 30 ++++++++++---
 3 files changed, 77 insertions(+), 34 deletions(-)

diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index c5948306e..6fe344523 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -28,7 +28,7 @@ class WebSupportApp(Sphinx):
 
 class WebSupport(object):
     def __init__(self, srcdir='', outdir='', search=None,
-                 comments=None, get_user=None):
+                 comments=None):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
@@ -36,9 +36,9 @@ class WebSupport(object):
         if search is not None:
             self.init_search(search)
 
-        self.init_comments(comments, get_user)
+        self.init_comments(comments)
     
-    def init_comments(self, comments, get_user):
+    def init_comments(self, comments):
         if isinstance(comments, sphinxcomments.CommentBackend):
             self.comments = comments
         elif comments is not None:
@@ -49,7 +49,7 @@ class WebSupport(object):
             db_path = path.join(self.outdir, 'comments', 'comments.db')
             ensuredir(path.dirname(db_path))
             engine = create_engine('sqlite:///%s' % db_path)
-            self.comments = SQLAlchemyComments(engine, get_user)
+            self.comments = SQLAlchemyComments(engine)
         
     def init_templating(self):
         import sphinx
@@ -94,10 +94,14 @@ class WebSupport(object):
         document['title'] = 'Search Results'
         return document
 
-    def get_comments(self, node_id):
-        return self.comments.get_comments(node_id)
+    def get_comments(self, node_id, user_id):
+        return self.comments.get_comments(node_id, user_id)
 
-    def add_comment(self, parent_id, text, displayed=True, user_id=None,
+    def add_comment(self, parent_id, text, displayed=True, username=None,
                     rating=0, time=None):
-        return self.comments.add_comment(parent_id, text, displayed, user_id,
-                                         rating, time)
+        return self.comments.add_comment(parent_id, text, displayed, 
+                                         username, rating, time)
+    
+    def process_vote(self, comment_id, user_id, value):
+        value = int(value)
+        self.comments.process_vote(comment_id, user_id, value)
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 8967bef61..5ca299246 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -2,7 +2,7 @@ from datetime import datetime
 
 from sqlalchemy.orm import sessionmaker
 
-from sphinx.websupport.comments.db import Base, Node, Comment
+from sphinx.websupport.comments.db import Base, Node, Comment, Vote
 
 Session = sessionmaker()
 
@@ -16,7 +16,8 @@ class CommentBackend(object):
     def post_build(self):
         pass
 
-    def add_comment(self, parent_id, text, displayed, user_id, rating, time):
+    def add_comment(self, parent_id, text, displayed, username, 
+                    rating, time):
         raise NotImplemented
 
     def get_comments(self, parent_id):
@@ -24,8 +25,7 @@ class CommentBackend(object):
 
 
 class SQLAlchemyComments(CommentBackend):
-    def __init__(self, engine, get_user):
-        self.get_user = get_user
+    def __init__(self, engine):
         self.engine = engine
         Base.metadata.bind = engine
         Base.metadata.create_all()
@@ -48,33 +48,51 @@ class SQLAlchemyComments(CommentBackend):
     def post_build(self):
         self.session.commit()
 
-    def add_comment(self, parent_id, text, displayed, user_id, rating, time):
+    def add_comment(self, parent_id, text, displayed, 
+                    username, rating, time):
         time = time or datetime.now()
 
         id = parent_id[1:]
         if parent_id[0] == 's':
             node = self.session.query(Node).filter(Node.id == id).first()
-            comment = Comment(text, displayed, user_id, rating, 
+            comment = Comment(text, displayed, username, rating, 
                               time, node=node)
         elif parent_id[0] == 'c':
             parent = self.session.query(Comment).filter(Comment.id == id).first()
-            comment = Comment(text, displayed, user_id, rating, 
+            comment = Comment(text, displayed, username, rating, 
                               time, parent=parent)
             
         self.session.add(comment)
         self.session.commit()
         return self.serializable(comment)
         
-    def get_comments(self, parent_id):
+    def get_comments(self, parent_id, user_id):
         parent_id = parent_id[1:]
         node = self.session.query(Node).filter(Node.id == parent_id).first()
         comments = []
         for comment in node.comments:
-            comments.append(self.serializable(comment))
+            comments.append(self.serializable(comment, user_id))
 
         return comments
 
-    def serializable(self, comment):
+    def process_vote(self, comment_id, user_id, value):
+        vote = self.session.query(Vote).filter(
+            Vote.comment_id == comment_id).filter(
+            Vote.user_id == user_id).first()
+        
+        comment = self.session.query(Comment).filter(
+            Comment.id == comment_id).first()
+
+        if vote is None:
+            vote = Vote(comment_id, user_id, value)
+            comment.rating += value
+        else:
+            comment.rating += value - vote.value
+            vote.value = value
+        self.session.add(vote)
+        self.session.commit()
+
+    def serializable(self, comment, user_id=None):
         time = {'year': comment.time.year,
                 'month': comment.time.month,
                 'day': comment.time.day,
@@ -84,22 +102,25 @@ class SQLAlchemyComments(CommentBackend):
                 'iso': comment.time.isoformat(),
                 'delta': self.pretty_delta(comment)}
 
+        vote = ''
+        if user_id is not None:
+            vote = self.session.query(Vote).filter(
+                Vote.comment_id == comment.id).filter(
+                Vote.user_id == user_id).first()
+            if vote is not None:
+                vote = vote.value 
+
         return {'text': comment.text,
-                'user': self.get_user(comment.user_id),
+                'username': comment.username or 'Anonymous',
                 'id': comment.id,
-                'rating': self.pretty_rating(comment),
+                'rating': comment.rating,
                 'time': time,
+                'vote': vote or 0,
                 'node': comment.node.id if comment.node else None,
                 'parent': comment.parent.id if comment.parent else None,
-                'children': [self.serializable(child) 
+                'children': [self.serializable(child, user_id) 
                              for child in comment.children]}
 
-    def pretty_rating(self, comment):
-        if comment.rating == 1:
-            return '%s point' % comment.rating
-        else:
-            return '%s points' % comment.rating
-
     def pretty_delta(self, comment):
         delta = datetime.now() - comment.time
         days = delta.days
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index ff731a9f1..22020b4b5 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -1,5 +1,6 @@
 from sqlalchemy import Column, Integer, Text, String, Boolean, ForeignKey,\
 DateTime
+from sqlalchemy.schema import UniqueConstraint
 from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import relation
 
@@ -23,9 +24,6 @@ class Node(Base):
         self.source = source
         self.treeloc = treeloc
 
-    def __repr__(self):
-        return '<Node %s#%s>' % (document, treeloc)
-
 class Comment(Base):
     __tablename__ = db_prefix + 'comments'
 
@@ -34,7 +32,7 @@ class Comment(Base):
     time = Column(DateTime, nullable=False)
     text = Column(Text, nullable=False)
     displayed = Column(Boolean, index=True, default=False)
-    user_id = Column(String(50), nullable=True)
+    username = Column(String(64))
 
     node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
     node = relation(Node, backref='comments')
@@ -42,12 +40,32 @@ class Comment(Base):
     parent_id = Column(Integer, ForeignKey(db_prefix + 'comments.id'))
     parent = relation('Comment', backref='children', remote_side=[id])
 
-    def __init__(self, text, displayed, user_id, rating, time, 
+    def __init__(self, text, displayed, username, rating, time, 
                  node=None, parent=None):
         self.text = text
         self.displayed = displayed
-        self.user_id = user_id
+        self.username = username
         self.rating = rating
         self.time = time
         self.node = node
         self.parent = parent
+
+class Vote(Base):
+    __tablename__ = db_prefix + 'vote'
+
+    id = Column(Integer, primary_key=True)
+    # -1 if downvoted, +1 if upvoted, 0 if voted then unvoted.
+    value = Column(Integer, nullable=False)
+    user_id = Column(Integer, index=True, nullable=False)
+
+    comment_id = Column(Integer, ForeignKey(db_prefix + 'comments.id'),
+                        nullable=False)
+    comment = relation(Comment, backref="votes")
+
+    __table_args__ = (UniqueConstraint(comment_id, user_id), {}) 
+
+    def __init__(self, comment_id, user_id, value):
+        self.value = value
+        self.user_id = user_id
+        self.comment_id = comment_id
+    

From a097429ec8d1e8fb8bcdc33653865d3111c1b3fd Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sun, 11 Jul 2010 14:15:30 -0500
Subject: [PATCH 030/127] Sortable comments

---
 sphinx/websupport/comments/__init__.py | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 5ca299246..395bde580 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -93,6 +93,8 @@ class SQLAlchemyComments(CommentBackend):
         self.session.commit()
 
     def serializable(self, comment, user_id=None):
+        delta = datetime.now() - comment.time
+
         time = {'year': comment.time.year,
                 'month': comment.time.month,
                 'day': comment.time.day,
@@ -100,7 +102,7 @@ class SQLAlchemyComments(CommentBackend):
                 'minute': comment.time.minute,
                 'second': comment.time.second,
                 'iso': comment.time.isoformat(),
-                'delta': self.pretty_delta(comment)}
+                'delta': self.pretty_delta(delta)}
 
         vote = ''
         if user_id is not None:
@@ -114,6 +116,7 @@ class SQLAlchemyComments(CommentBackend):
                 'username': comment.username or 'Anonymous',
                 'id': comment.id,
                 'rating': comment.rating,
+                'age': delta.seconds,
                 'time': time,
                 'vote': vote or 0,
                 'node': comment.node.id if comment.node else None,
@@ -121,8 +124,7 @@ class SQLAlchemyComments(CommentBackend):
                 'children': [self.serializable(child, user_id) 
                              for child in comment.children]}
 
-    def pretty_delta(self, comment):
-        delta = datetime.now() - comment.time
+    def pretty_delta(self, delta):
         days = delta.days
         seconds = delta.seconds
         hours = seconds / 3600

From 1aceea73a98308be404e749380ec541a884a29e6 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sun, 11 Jul 2010 18:25:52 -0500
Subject: [PATCH 031/127] Enable comments by default.

---
 sphinx/websupport/api.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
index 6fe344523..0662f371b 100644
--- a/sphinx/websupport/api.py
+++ b/sphinx/websupport/api.py
@@ -41,7 +41,7 @@ class WebSupport(object):
     def init_comments(self, comments):
         if isinstance(comments, sphinxcomments.CommentBackend):
             self.comments = comments
-        elif comments is not None:
+        else:
             # If a CommentBackend isn't provided, use the default
             # SQLAlchemy backend with an SQLite db.
             from sphinx.websupport.comments import SQLAlchemyComments

From a1c99c96030d14d511dcdc39603353da17064f69 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sun, 11 Jul 2010 18:33:42 -0500
Subject: [PATCH 032/127] Move api.py into __init__.py

---
 sphinx/websupport/__init__.py | 99 ++++++++++++++++++++++++++++++++++-
 1 file changed, 97 insertions(+), 2 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index d23e80a7a..3ee4aac7a 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -3,10 +3,105 @@
     sphinx.websupport
     ~~~~~~~~~~~~~~~~~
 
-    Web Support Package
+    Base Module for web support functions.
 
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 
-from sphinx.websupport.api import WebSupport
+import cPickle as pickle
+from os import path
+from datetime import datetime
+
+from jinja2 import Environment, FileSystemLoader
+
+from sphinx.application import Sphinx
+from sphinx.util.osutil import ensuredir
+from sphinx.websupport.search import search_adapters
+from sphinx.websupport import comments as sphinxcomments
+
+class WebSupportApp(Sphinx):
+    def __init__(self, *args, **kwargs):
+        self.search = kwargs.pop('search', None)
+        self.comments = kwargs.pop('comments', None)
+        Sphinx.__init__(self, *args, **kwargs)
+
+class WebSupport(object):
+    def __init__(self, srcdir='', outdir='', search=None,
+                 comments=None):
+        self.srcdir = srcdir
+        self.outdir = outdir or path.join(self.srcdir, '_build',
+                                          'websupport')
+        self.init_templating()
+        if search is not None:
+            self.init_search(search)
+
+        self.init_comments(comments)
+    
+    def init_comments(self, comments):
+        if isinstance(comments, sphinxcomments.CommentBackend):
+            self.comments = comments
+        else:
+            # If a CommentBackend isn't provided, use the default
+            # SQLAlchemy backend with an SQLite db.
+            from sphinx.websupport.comments import SQLAlchemyComments
+            from sqlalchemy import create_engine
+            db_path = path.join(self.outdir, 'comments', 'comments.db')
+            ensuredir(path.dirname(db_path))
+            engine = create_engine('sqlite:///%s' % db_path)
+            self.comments = SQLAlchemyComments(engine)
+        
+    def init_templating(self):
+        import sphinx
+        template_path = path.join(path.dirname(sphinx.__file__),
+                                  'themes', 'basic')
+        loader = FileSystemLoader(template_path)
+        self.template_env = Environment(loader=loader)
+
+    def init_search(self, search):
+        mod, cls = search_adapters[search]
+        search_class = getattr(__import__('sphinx.websupport.search.' + mod, 
+                                          None, None, [cls]), cls)
+        search_path = path.join(self.outdir, 'search')
+        self.search = search_class(search_path)
+        self.results_template = \
+            self.template_env.get_template('searchresults.html')
+
+    def build(self, **kwargs):
+        doctreedir = kwargs.pop('doctreedir', 
+                                path.join(self.outdir, 'doctrees'))
+        app = WebSupportApp(self.srcdir, self.srcdir,
+                            self.outdir, doctreedir, 'websupport',
+                            search=self.search,
+                            comments=self.comments)
+        self.comments.pre_build()
+        app.build()
+        self.comments.post_build()
+
+    def get_document(self, docname):
+        infilename = path.join(self.outdir, docname + '.fpickle')
+        f = open(infilename, 'rb')
+        document = pickle.load(f)
+        return document
+
+    def get_search_results(self, q):
+        results, results_found, results_displayed = self.search.query(q)
+        ctx = {'search_performed': True,
+               'search_results': results,
+               'q': q}
+        document = self.get_document('search')
+        document['body'] = self.results_template.render(ctx)
+        document['title'] = 'Search Results'
+        return document
+
+    def get_comments(self, node_id, user_id):
+        return self.comments.get_comments(node_id, user_id)
+
+    def add_comment(self, parent_id, text, displayed=True, username=None,
+                    rating=0, time=None):
+        return self.comments.add_comment(parent_id, text, displayed, 
+                                         username, rating, time)
+    
+    def process_vote(self, comment_id, user_id, value):
+        value = int(value)
+        self.comments.process_vote(comment_id, user_id, value)

From cf06e98ebd910baa86a534c70d6030afc5681cef Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 12 Jul 2010 01:41:39 -0500
Subject: [PATCH 033/127] Lots of documentation and a few small API changes

---
 doc/web/api.rst               |  32 ++--
 doc/web/quickstart.rst        | 283 +++++++++++++++++++++++-----------
 sphinx/websupport/__init__.py | 147 ++++++++++++++++--
 sphinx/websupport/api.py      | 107 -------------
 4 files changed, 346 insertions(+), 223 deletions(-)
 delete mode 100644 sphinx/websupport/api.py

diff --git a/doc/web/api.rst b/doc/web/api.rst
index ef8e47088..0b86309c0 100644
--- a/doc/web/api.rst
+++ b/doc/web/api.rst
@@ -1,22 +1,32 @@
 .. _websupportapi:
 
-Web Support API
-===============
+.. currentmodule:: sphinx.websupport
+
+The WebSupport Class
+====================
 
-.. module:: sphinx.websupport.api
 .. class:: WebSupport
 
-   The :class:`WebSupport` class provides a central interface for 
-   working with Sphinx documentation.
+   The main API class for the web support package. All interactions
+   with the web support package should occur through this class.
 
-.. method:: init(srcdir='', outdir='')
+   :param srcdir: the directory containing the reStructuredText files
+   :param outdir: the directory in which to place the built data
+   :param search: the search system to use
+   :param comments: an instance of a CommentBackend
+    
+Methods
+~~~~~~~
 
-   Initialize attributes.
+.. automethod:: sphinx.websupport.WebSupport.build
 
-.. method:: build()
+.. automethod:: sphinx.websupport.WebSupport.get_document
 
-   Build the data used by the web support package.
+.. automethod:: sphinx.websupport.WebSupport.get_comments
 
-.. method:: get_document(docname)
+.. automethod:: sphinx.websupport.WebSupport.add_comment
+
+.. automethod:: sphinx.websupport.WebSupport.process_vote
+
+.. automethod:: sphinx.websupport.WebSupport.get_search_results
 
-   Retrieve the context dictionary corresponding to the *docname*.
diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
index d519323eb..ef01d0d7b 100644
--- a/doc/web/quickstart.rst
+++ b/doc/web/quickstart.rst
@@ -3,118 +3,215 @@
 Web Support Quick Start
 =======================
 
-Getting Started
-~~~~~~~~~~~~~~~
-
-To use the :ref:`websupportapi` in your application you must import
-the :class:`~sphinx.websupport.api.WebSupport` object::
-
-    from sphinx.websupport import support
-
-This provides a reference to a :class:`~sphinx.websupport.api.WebSupport`
-object. You will then need to provide some information about your 
-environment::
-
-    support.init(srcdir='/path/to/rst/sources/',
-                 outdir='/path/to/build/outdir',
-		 search='xapian')
-
-Note: You only need to provide a srcdir if you are building documentation.
-
 Building Documentation Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In order to use the web support package in a webapp, you will need to
-build the data it uses. This data includes document data used to display
-documentation and search indexes. To build this data, call the build method::
+To make use of the web support package in your application you will
+need to build that data it uses. This data includes pickle files representing
+documents, search indices, and node data that is used to track where
+comments and other things are in a document. Do do this you will need
+to create an instance of the :class:`~sphinx.websupport.api.WebSupport` 
+class and call it's :meth:`~sphinx.websupport.WebSupport.build` method::
+
+    from sphinx.websupport import WebSupport
+
+    support = WebSupport(srcdir='/path/to/rst/sources/',
+                         outdir='/path/to/build/outdir',
+		         search='xapian')
 
     support.build()
 
-This will create the data the web support package needs and place
-it in *outdir*. 
+This will read reStructuredText sources from `srcdir` and place the
+necessary data in `outdir`. This directory contains all the data needed
+to display documents, search through documents, and add comments to
+documents.
 
-Accessing Document Data
-~~~~~~~~~~~~~~~~~~~~~~~
+Integrating Sphinx Documents Into Your Webapp
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To access document data, call the get_document(docname) method. For example, 
-to retrieve the "contents" document, do this::
-
-    contents_doc = support.get_document('contents')
-
-This will return a dictionary containing the context you need to render
-a document.
-
-Performing Searches
-~~~~~~~~~~~~~~~~~~~
-
-To perform a search, call the get_search_results(q) method, with *q* being
-the string to be searched for::
-
-    q = request.GET['q']
-    search_doc = support.get_search_results(q)
-
-This will return a dictionary in the same format as get_document() returns.
-
-Full Example
-~~~~~~~~~~~~
-
-A more useful example, in the form of a `Flask <http://flask.pocoo.org/>`_
-application is::
-
-    from flask import Flask, render_template
-    from sphinx.websupport import support
-
-    app = Flask(__name__)
-
-    support.init(outdir='/path/to/sphinx/data')
+Now that you have the data, it's time to use it for something useful.
+Start off by creating a :class:`~sphinx.websupport.WebSupport` object
+for your application::
     
-    @app.route('/docs/<path:docname>')
+    from sphinx.websupport import WebSupport
+
+    support = WebSupport(datadir='/path/to/the/data',
+                         search='xapian')
+
+You'll only need one of these for each set of documentation you will be
+working with. You can then call it's 
+:meth:`~sphinx.websupport.WebSupport.get_document` method to access
+individual documents.
+
+    contents = support.get_document('contents')
+
+This will return a dictionary containing the following items:
+
+* **body**: The main body of the document as HTML
+* **sidebar**: The sidebar of the document as HTML  
+* **relbar**: A div containing links to related documents
+* **title**: The title of the document
+
+This dict can then be used as context for templates. The goal is to be
+easy to integrate with your existing templating system. An example using 
+`Jinja2 <http://jinja.pocoo.org/2/>`_ is:
+
+.. sourcecode:: html+jinja
+
+    {%- extends "layout.html" %}
+
+    {%- block title %}
+      {{ document.title }}
+    {%- endblock %}
+
+    {%- block relbar %}
+      {{ document.relbar|safe }}
+    {%- endblock %}
+
+    {%- block body %}
+      {{ document.body|safe }}
+    {%- endblock %}
+
+    {%- block sidebar %}
+      {{ document.sidebar|safe }}
+    {%- endblock %}
+
+Most likely you'll want to create one function that can handle all of
+document requests. An example `Flask <http://flask.pocoo.org/>`_ function
+that performs this is::
+
+    @app.route('/<path:docname>')
     def doc(docname):
         document = support.get_document(docname)
         return render_template('doc.html', document=document)
 
-    @app.route('/docs/search')
+This captures the request path, and passes it directly to 
+:meth:`~sphinx.websupport.WebSupport.get_document`, which retrieves
+the correct document.
+
+.. note::
+
+   This only works works if your documentation is served from your
+   document root. If it is served from another directory, you will
+   need to prefix the url route with that directory::
+
+       @app.route('/docs/<path:docname>')
+
+Performing Searches
+~~~~~~~~~~~~~~~~~~~
+
+To use the search form built-in to the Sphinx sidebar, create a function
+to handle requests to the url 'search' relative to the documentation root.
+The user's search query will be in the GET parameters, with the key `q`.
+Then use the :meth:`~sphinx.websupport.WebSupport.get_search_results` method
+to retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that 
+would be like this::
+
+    @app.route('/search')
     def search():
-        document = support.get_search_results(request.args.get('q', ''))
-	return render_template('doc.html', document=document)
+        q = request.args.get('q')
+        document = support.get_search_results(q)
+        return render_template('doc.html', document=document)
 
-In the previous example the doc.html template would look something 
-like this::
+Note that we used the same template to render our search results as we
+did to render our documents. That's because 
+:meth:`~sphinx.websupport.WebSupport.get_search_results` returns a context
+dict in the same format as 
+:meth:`~sphinx.websupport.WebSupport.get_document`.
 
-    {% extends "base.html" %}
+Comments
+~~~~~~~~
 
-    {% block title %}
-      {{ document.title }}
-    {% endblock %}
+The web support package provides a way to attach comments to some nodes
+in your document. It marks these nodes by adding a class and id to these
+nodes. A client side script can then locate these nodes, and manipulate
+them to allow commenting. A jquery script is also being developed that will
+be included when it's complete. For now you can find the script here:
+`websupport.js <http://bit.ly/cyaRaF>`_.
 
-    {% block extra_js %}
-      <script type="text/javascript" src="/static/jquery.js"></script>
-      <script type="text/javascript">
-        <!--
-        $(document).ready(function() {
-          $(".spxcmt").append(' <a href="#" class="sphinx_comment"><img src="/static/comment.png" /></a>');
-          $("a.sphinx_comment").click(function() {
-            id = $(this).parent().attr('id');
-            alert('[ comment stub ' + id + ' ]');
-            return false;
-          });
-        });
-        -->
-      </script>
-    {% endblock %}
+If you use the script that is included, you will have to define some
+simple templates that the script uses to display comments. The first 
+template defines the layout for the popup div used to display comments:
 
-    {% block relbar %}
-      {{ document.relbar|safe }}
-    {% endblock %}
+.. sourcecode:: guess
 
-    {% block body %}
-      {{ document.body|safe }}
-    {% endblock %}
+   <script type="text/html" id="popup_template">
+     <div class="popup_comment">
+       <a id="comment_close" href="#">x</a>
+       <h1>Comments</h1>
+       <form method="post" id="comment_form" action="/docs/add_comment">
+ 	 <textarea name="comment"></textarea>
+	 <input type="submit" value="add comment" id="comment_button" />
+	 <input type="hidden" name="parent" />
+       <p class="sort_options">
+	 Sort by: 
+	 <a href="#" class="sort_option" id="rating">top</a>
+	 <a href="#" class="sort_option" id="ascage">newest</a>
+	 <a href="#" class="sort_option" id="age">oldest</a>
+       </p>
+       </form>
+       <h3 id="comment_notification">loading comments... <img src="/static/ajax-loader.gif" alt="" /></h3>
+       <ul id="comment_ul"></ul>
+     </div>
+     <div id="focuser"></div>
+   </script> 
 
-    {% block sidebar %}
-      {{ document.sidebar|safe }}
-    {% endblock %}
+The next templat is an `li` that contains the form used to 
+reply to a comment:
+
+.. sourcecode:: guess
+
+   <script type="text/html" id="reply_template">
+     <li>
+       <div class="reply_div" id="rd<%id%>">
+	 <form id="rf<%id%>">
+	   <textarea name="comment"></textarea>
+           <input type="submit" value="add reply" />
+           <input type="hidden" name="parent" value="c<%id%>" />
+         </form>
+       </div>
+     </li>
+   </script>
+
+The final template contains HTML that will be used to display comments
+in the comment tree:
+
+.. sourcecode:: guess
+
+   <script type="text/html" id="comment_template">
+     <div  id="cd<%id%>" class="spxcdiv">
+       <div class="vote">
+	 <div class="arrow">
+	   <a href="#" id="uv<%id%>" class="vote">
+	     <img src="<%upArrow%>" />
+	   </a>
+	   <a href="#" id="uu<%id%>" class="un vote">
+	     <img src="<%upArrowPressed%>" />
+	   </a>
+	 </div>
+	 <div class="arrow">
+	   <a href="#" id="dv<%id%>" class="vote">
+	     <img src="<%downArrow%>" id="da<%id%>" />
+	   </a>
+	   <a href="#" id="du<%id%>" class="un vote">
+	     <img src="<%downArrowPressed%>" />
+	   </a>
+	 </div>
+       </div>
+       <div class="comment_content">
+	 <p class="tagline comment">
+	   <span class="user_id"><%username%></span>
+	   <span class="rating"><%pretty_rating%></span>
+	   <span class="delta"><%time.delta%></span>
+	 </p>
+	 <p class="comment_text comment"><%text%></p>
+	 <p class="comment_opts comment">
+	   <a href="#" class="reply" id="rl<%id%>">reply</a>
+	   <a href="#" class="close_reply" id="cr<%id%>">hide</a>
+	 </p>
+	 <ul class="children" id="cl<%id%>"></ul>
+       </div>
+       <div class="clearleft"></div>
+     </div>
+   </script>
 
-    {% block relbar %}
-      {{ document.relbar|safe }}
-    {% endblock %}
\ No newline at end of file
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 3ee4aac7a..2dbbe3197 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -27,18 +27,25 @@ class WebSupportApp(Sphinx):
         Sphinx.__init__(self, *args, **kwargs)
 
 class WebSupport(object):
-    def __init__(self, srcdir='', outdir='', search=None,
+    """The main API class for the web support package. All interactions
+    with the web support package should occur through this class.
+    """
+
+    def __init__(self, srcdir='', outdir='', datadir='', search=None,
                  comments=None):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
-        self.init_templating()
-        if search is not None:
-            self.init_search(search)
+        self._init_templating()
 
-        self.init_comments(comments)
+        self.outdir = outdir or datadir
+
+        if search is not None:
+            self._init_search(search)
+
+        self._init_comments(comments)
     
-    def init_comments(self, comments):
+    def _init_comments(self, comments):
         if isinstance(comments, sphinxcomments.CommentBackend):
             self.comments = comments
         else:
@@ -51,14 +58,14 @@ class WebSupport(object):
             engine = create_engine('sqlite:///%s' % db_path)
             self.comments = SQLAlchemyComments(engine)
         
-    def init_templating(self):
+    def _init_templating(self):
         import sphinx
         template_path = path.join(path.dirname(sphinx.__file__),
                                   'themes', 'basic')
         loader = FileSystemLoader(template_path)
         self.template_env = Environment(loader=loader)
 
-    def init_search(self, search):
+    def _init_search(self, search):
         mod, cls = search_adapters[search]
         search_class = getattr(__import__('sphinx.websupport.search.' + mod, 
                                           None, None, [cls]), cls)
@@ -67,24 +74,65 @@ class WebSupport(object):
         self.results_template = \
             self.template_env.get_template('searchresults.html')
 
-    def build(self, **kwargs):
-        doctreedir = kwargs.pop('doctreedir', 
-                                path.join(self.outdir, 'doctrees'))
+    def build(self):
+        """Build the documentation. Places the data into the `outdir`
+        directory. Use it like this::
+
+            support = WebSupport(srcdir, outdir, search)
+            support.build()
+
+        This will read reStructured text files from `srcdir`. Then it
+        build the pickles and search index, placing them into `outdir`.
+        It will also save node data to the database.
+        """
+        doctreedir = path.join(self.outdir, 'doctrees')
         app = WebSupportApp(self.srcdir, self.srcdir,
                             self.outdir, doctreedir, 'websupport',
                             search=self.search,
                             comments=self.comments)
+        # TODO:
+        # Hook comments into Sphinx signals.
         self.comments.pre_build()
         app.build()
         self.comments.post_build()
 
     def get_document(self, docname):
+        """Load and return a document from a pickle. The document will
+        be a dict object which can be used to render a template::
+
+            support = WebSupport(outdir=outdir)
+            support.get_document('index')
+            
+        In most cases `docname` will be taken from the request path and 
+        passed directly to this function. In Flask, that would be something
+        like this::
+
+            @app.route('/<path:docname>')
+            def index(docname):
+                q = request.args.get('q')
+                document = support.get_search_results(q)
+                render_template('doc.html', document=document)
+
+        The document dict that is returned contains the following items
+        to be used during template rendering.
+
+        :param docname: the name of the document to load.
+        """
         infilename = path.join(self.outdir, docname + '.fpickle')
         f = open(infilename, 'rb')
         document = pickle.load(f)
         return document
 
     def get_search_results(self, q):
+        """Perform a search for the query `q`, and create a set
+        of search results. Then render the search results as html and
+        return a context dict like the one created by
+        :meth:`get_document`::
+        
+            document = support.get_search_results(q)
+
+        :param q: the search query
+        """
         results, results_found, results_displayed = self.search.query(q)
         ctx = {'search_performed': True,
                'search_results': results,
@@ -94,14 +142,89 @@ class WebSupport(object):
         document['title'] = 'Search Results'
         return document
 
-    def get_comments(self, node_id, user_id):
+    def get_comments(self, node_id, user_id=None):
+        """Get the comments associated with `node_id`. If `user_id` is
+        given vote information will be included with the returned comments.
+        The default CommentBackend returns a list of dicts. Each dict
+        represents a comment, and has the following items:
+
+        ============ ======================================================
+        Key          Contents
+        ============ ======================================================
+        text         The comment text.
+        username     The username that was stored with the comment.
+        id           The comment's unique identifier.
+        rating       The comment's current rating.
+        age          The time in seconds since the comment was added.
+        time         A dict containing time information. It contains the
+                     following keys: year, month, day, hour, minute, second,
+                     iso, and delta. `iso` is the time formatted in ISO
+                     8601 format. `delta` is a printable form of how old
+                     the comment is (e.g. "3 hours ago").
+        vote         If `user_id` was given, this will be an integer
+                     representing the vote. 1 for an upvote, -1 for a 
+                     downvote, or 0 if unvoted.
+        node         The node that the comment is attached to. If the
+                     comment's parent is another comment rather than a
+                     node, this will be null.
+        parent       The id of the comment that this comment is attached 
+                     to if it is not attached to a node.
+        children     A list of all children, in this format.
+        ============ ======================================================
+
+        :param node_id: the id of the node to get comments for.
+        :param user_id: the id of the user viewing the comments.
+        """
         return self.comments.get_comments(node_id, user_id)
 
     def add_comment(self, parent_id, text, displayed=True, username=None,
                     rating=0, time=None):
+        """Add a comment to a node or another comment. `parent_id` will have
+        a one letter prefix, distinguishing between node parents and 
+        comment parents, 'c' and 's' respectively. This function will
+        return the comment in the same format as :meth:`get_comments`.
+        Usage is simple::
+
+            comment = support.add_comment(parent_id, text)
+        
+        If you would like to store a username with the comment, pass
+        in the optional `username` keyword argument::
+
+            comment = support.add_comment(parent_id, text, username=username)
+
+        :param parent_id: the prefixed id of the comment's parent.
+        :param text: the text of the comment.
+        :param displayed: for future use...
+        :param username: the username of the user making the comment.
+        :param rating: the starting rating of the comment, defaults to 0.
+        :param time: the time the comment was created, defaults to now.
+        """
         return self.comments.add_comment(parent_id, text, displayed, 
                                          username, rating, time)
     
     def process_vote(self, comment_id, user_id, value):
+        """Process a user's vote. The web support package relies
+        on the API user to perform authentication. The API user will 
+        typically receive a comment_id and value from a form, and then
+        make sure the user is authenticated. A unique integer `user_id` 
+        (usually the User primary key) must be passed in, which will 
+        also be used to retrieve the user's past voting information. 
+        An example, once again in Flask::
+
+            @app.route('/docs/process_vote', methods=['POST'])
+            def process_vote():
+                if g.user is None:
+                    abort(401)
+                comment_id = request.form.get('comment_id')
+                value = request.form.get('value')
+                if value is None or comment_id is None:
+                    abort(400)
+                support.process_vote(comment_id, g.user.id, value)
+                return "success"
+
+        :param comment_id: the comment being voted on
+        :param user_id: the unique integer id of the user voting
+        :param value: 1 for an upvote, -1 for a downvote, 0 for an unvote.
+        """
         value = int(value)
         self.comments.process_vote(comment_id, user_id, value)
diff --git a/sphinx/websupport/api.py b/sphinx/websupport/api.py
deleted file mode 100644
index 0662f371b..000000000
--- a/sphinx/websupport/api.py
+++ /dev/null
@@ -1,107 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-    sphinx.websupport.api
-    ~~~~~~~~~~~~~~~~~~~~~
-
-    All API functions.
-
-    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
-
-import cPickle as pickle
-from os import path
-from datetime import datetime
-
-from jinja2 import Environment, FileSystemLoader
-
-from sphinx.application import Sphinx
-from sphinx.util.osutil import ensuredir
-from sphinx.websupport.search import search_adapters
-from sphinx.websupport import comments as sphinxcomments
-
-class WebSupportApp(Sphinx):
-    def __init__(self, *args, **kwargs):
-        self.search = kwargs.pop('search', None)
-        self.comments = kwargs.pop('comments', None)
-        Sphinx.__init__(self, *args, **kwargs)
-
-class WebSupport(object):
-    def __init__(self, srcdir='', outdir='', search=None,
-                 comments=None):
-        self.srcdir = srcdir
-        self.outdir = outdir or path.join(self.srcdir, '_build',
-                                          'websupport')
-        self.init_templating()
-        if search is not None:
-            self.init_search(search)
-
-        self.init_comments(comments)
-    
-    def init_comments(self, comments):
-        if isinstance(comments, sphinxcomments.CommentBackend):
-            self.comments = comments
-        else:
-            # If a CommentBackend isn't provided, use the default
-            # SQLAlchemy backend with an SQLite db.
-            from sphinx.websupport.comments import SQLAlchemyComments
-            from sqlalchemy import create_engine
-            db_path = path.join(self.outdir, 'comments', 'comments.db')
-            ensuredir(path.dirname(db_path))
-            engine = create_engine('sqlite:///%s' % db_path)
-            self.comments = SQLAlchemyComments(engine)
-        
-    def init_templating(self):
-        import sphinx
-        template_path = path.join(path.dirname(sphinx.__file__),
-                                  'themes', 'basic')
-        loader = FileSystemLoader(template_path)
-        self.template_env = Environment(loader=loader)
-
-    def init_search(self, search):
-        mod, cls = search_adapters[search]
-        search_class = getattr(__import__('sphinx.websupport.search.' + mod, 
-                                          None, None, [cls]), cls)
-        search_path = path.join(self.outdir, 'search')
-        self.search = search_class(search_path)
-        self.results_template = \
-            self.template_env.get_template('searchresults.html')
-
-    def build(self, **kwargs):
-        doctreedir = kwargs.pop('doctreedir', 
-                                path.join(self.outdir, 'doctrees'))
-        app = WebSupportApp(self.srcdir, self.srcdir,
-                            self.outdir, doctreedir, 'websupport',
-                            search=self.search,
-                            comments=self.comments)
-        self.comments.pre_build()
-        app.build()
-        self.comments.post_build()
-
-    def get_document(self, docname):
-        infilename = path.join(self.outdir, docname + '.fpickle')
-        f = open(infilename, 'rb')
-        document = pickle.load(f)
-        return document
-
-    def get_search_results(self, q):
-        results, results_found, results_displayed = self.search.query(q)
-        ctx = {'search_performed': True,
-               'search_results': results,
-               'q': q}
-        document = self.get_document('search')
-        document['body'] = self.results_template.render(ctx)
-        document['title'] = 'Search Results'
-        return document
-
-    def get_comments(self, node_id, user_id):
-        return self.comments.get_comments(node_id, user_id)
-
-    def add_comment(self, parent_id, text, displayed=True, username=None,
-                    rating=0, time=None):
-        return self.comments.add_comment(parent_id, text, displayed, 
-                                         username, rating, time)
-    
-    def process_vote(self, comment_id, user_id, value):
-        value = int(value)
-        self.comments.process_vote(comment_id, user_id, value)

From df10a2875eeb29dec4fd714d9c218dab6791b081 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 12 Jul 2010 12:15:01 -0500
Subject: [PATCH 034/127] More documentation

---
 doc/web/quickstart.rst | 94 +++++++++++++++++++++++++++++++++++-------
 doc/websupport.rst     |  3 +-
 2 files changed, 82 insertions(+), 15 deletions(-)

diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
index ef01d0d7b..16c650c27 100644
--- a/doc/web/quickstart.rst
+++ b/doc/web/quickstart.rst
@@ -6,10 +6,10 @@ Web Support Quick Start
 Building Documentation Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To make use of the web support package in your application you will
+To make use of the web support package in your application you'll
 need to build that data it uses. This data includes pickle files representing
 documents, search indices, and node data that is used to track where
-comments and other things are in a document. Do do this you will need
+comments and other things are in a document. To do this you will need
 to create an instance of the :class:`~sphinx.websupport.api.WebSupport` 
 class and call it's :meth:`~sphinx.websupport.WebSupport.build` method::
 
@@ -29,7 +29,7 @@ documents.
 Integrating Sphinx Documents Into Your Webapp
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now that you have the data, it's time to use it for something useful.
+Now that you have the data, it's time to do something useful with it.
 Start off by creating a :class:`~sphinx.websupport.WebSupport` object
 for your application::
     
@@ -41,7 +41,7 @@ for your application::
 You'll only need one of these for each set of documentation you will be
 working with. You can then call it's 
 :meth:`~sphinx.websupport.WebSupport.get_document` method to access
-individual documents.
+individual documents::
 
     contents = support.get_document('contents')
 
@@ -86,7 +86,7 @@ that performs this is::
         return render_template('doc.html', document=document)
 
 This captures the request path, and passes it directly to 
-:meth:`~sphinx.websupport.WebSupport.get_document`, which retrieves
+:meth:`~sphinx.websupport.WebSupport.get_document`, which then retrieves
 the correct document.
 
 .. note::
@@ -116,8 +116,8 @@ would be like this::
 Note that we used the same template to render our search results as we
 did to render our documents. That's because 
 :meth:`~sphinx.websupport.WebSupport.get_search_results` returns a context
-dict in the same format as 
-:meth:`~sphinx.websupport.WebSupport.get_document`.
+dict in the same format that
+:meth:`~sphinx.websupport.WebSupport.get_document` does.
 
 Comments
 ~~~~~~~~
@@ -125,13 +125,32 @@ Comments
 The web support package provides a way to attach comments to some nodes
 in your document. It marks these nodes by adding a class and id to these
 nodes. A client side script can then locate these nodes, and manipulate
-them to allow commenting. A jquery script is also being developed that will
-be included when it's complete. For now you can find the script here:
-`websupport.js <http://bit.ly/cyaRaF>`_.
+them to allow commenting. A `jQuery <http://jquery.com>`_ script is also 
+being developed that will be included when it's complete. For now you can 
+find the script here: `websupport.js <http://bit.ly/cyaRaF>`_. This script 
+will use AJAX for all communications with the server. You can create your 
+own script for the front end if this doesn't meet your needs. More 
+information on that can be found :ref:`here <websupportfrontend>`.
 
-If you use the script that is included, you will have to define some
-simple templates that the script uses to display comments. The first 
-template defines the layout for the popup div used to display comments:
+Before loading this script in your page, you need to create a COMMENT_OPTIONS
+object describing how the script should function. In the simplest case you
+will just need tell the script whether the current user is allowed to vote.
+Once this is done you can import the script as you would any other:
+
+.. sourcecode:: guess
+
+    <script type="text/javascript">
+      var COMMENT_OPTIONS =  {
+        {%- if g.user %}
+	  voting: true,
+	{%- endif %}
+      }
+    </script>
+    <script type="text/javascript" src="/static/websupport.js></script>
+
+You will then need to define some templates that the script uses to 
+display comments. The first template defines the layout for the popup 
+div used to display comments:
 
 .. sourcecode:: guess
 
@@ -156,7 +175,7 @@ template defines the layout for the popup div used to display comments:
      <div id="focuser"></div>
    </script> 
 
-The next templat is an `li` that contains the form used to 
+The next template is an `li` that contains the form used to 
 reply to a comment:
 
 .. sourcecode:: guess
@@ -215,3 +234,50 @@ in the comment tree:
      </div>
    </script>
 
+Now that this is done it's time to define the functions that handle
+the AJAX calls from the script. You will need three functions. The first
+function is used to add a new comment, and will call the web support method
+:meth:`~sphinx.websupport.WebSupport.add_comment`::
+
+    @app.route('/docs/add_comment', methods=['POST'])
+    def add_comment():
+        parent_id = request.form.get('parent', '')
+        text = request.form.get('text', '')
+        username = g.user.name if g.user is not None else 'Anonymous'
+        comment = support.add_comment(parent_id, text, username=username)
+        return jsonify(comment=comment)
+
+Then next function handles the retrieval of comments for a specific node, 
+and is aptly named :meth:`~sphinx.websupport.WebSupport.get_comments`::
+
+    @app.route('/docs/get_comments')
+    def get_comments():
+        user_id = g.user.id if g.user else None
+        parent_id = request.args.get('parent', '')
+        comments = support.get_comments(parent_id, user_id)
+        return jsonify(comments=comments)
+
+The final function that is needed will call
+:meth:`~sphinx.websupport.WebSupport.process_vote`, and will handle user
+votes on comments::
+
+    @app.route('/docs/process_vote', methods=['POST'])
+    def process_vote():
+        if g.user is None:
+            abort(401)
+        comment_id = request.form.get('comment_id')
+        value = request.form.get('value')
+        if value is None or comment_id is None:
+            abort(400)
+        support.process_vote(comment_id, g.user.id, value)
+        return "success"
+
+.. note::
+
+   Authentication is left up to your existing web application. If you do
+   not have an existing authentication system there are many readily 
+   available for different frameworks. The web support system stores only
+   the user's unique integer `user_id` and uses this both for storing votes 
+   and retrieving vote information. It is up to you to ensure that the 
+   user_id passed in is unique, and that the user is authenticated. The 
+   default backend will only allow one vote per comment per `user_id`.
diff --git a/doc/websupport.rst b/doc/websupport.rst
index 2927f5a79..e8fc238b8 100644
--- a/doc/websupport.rst
+++ b/doc/websupport.rst
@@ -10,4 +10,5 @@ into your web application. To learn more read the
 .. toctree::
 
    web/quickstart
-   web/api
\ No newline at end of file
+   web/api
+   web/frontend
\ No newline at end of file

From 77515dee798716ee5949d68e650ee408f3f535c6 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 12 Jul 2010 12:41:32 -0500
Subject: [PATCH 035/127] added frontend.rst

---
 doc/web/frontend.rst | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 doc/web/frontend.rst

diff --git a/doc/web/frontend.rst b/doc/web/frontend.rst
new file mode 100644
index 000000000..5ffe16674
--- /dev/null
+++ b/doc/web/frontend.rst
@@ -0,0 +1,6 @@
+.. _websupportfrontend:
+
+Web Support Frontend
+====================
+
+More coming soon.
\ No newline at end of file

From fa1e30c155d46b22d78b56eebc1650d1b564d4ba Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 12 Jul 2010 14:25:08 -0500
Subject: [PATCH 036/127] updated CHANGES.jacobmason

---
 CHANGES.jacobmason | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/CHANGES.jacobmason b/CHANGES.jacobmason
index fe7c57fbb..bd87c71c6 100644
--- a/CHANGES.jacobmason
+++ b/CHANGES.jacobmason
@@ -2,5 +2,14 @@ May 30: Added files builders/websupport.py, writers/websupport.py,
 websupport/api.py, and websupport/document.api. Provides a rudimentary 
 method of building websupport data, and rendering it as html.
 
-May 31-June 4: Continued changing way web support data is represented
-and accessed.
\ No newline at end of file
+May 31-June 10: Continued changing way web support data is represented
+and accessed.
+
+June 14 - June 17: Continued making improvements to the web support package 
+and demo web application. Included sidebars, navlinks etc...
+
+June 21 - June 26: Implement server side search with two search adapters,
+one for Xapian and one for Whoosh
+
+June 28 - July 12: Implement voting system on the backend, and created a
+jQuery script to handle voting on the frontend.
\ No newline at end of file

From 8ff41de37b90dc7fbaaeefdb3d40cf5ac650fd23 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 13 Jul 2010 15:33:12 -0500
Subject: [PATCH 037/127] API tweaks and more documentation

---
 doc/websupport.rst                       |  3 +-
 sphinx/websupport/__init__.py            | 15 ++--
 sphinx/websupport/search/__init__.py     | 88 +++++++++++++++++++++---
 sphinx/websupport/search/whooshsearch.py |  8 +--
 sphinx/websupport/search/xapiansearch.py |  6 +-
 5 files changed, 95 insertions(+), 25 deletions(-)

diff --git a/doc/websupport.rst b/doc/websupport.rst
index e8fc238b8..1b6725df1 100644
--- a/doc/websupport.rst
+++ b/doc/websupport.rst
@@ -11,4 +11,5 @@ into your web application. To learn more read the
 
    web/quickstart
    web/api
-   web/frontend
\ No newline at end of file
+   web/frontend
+   web/searchadapters
\ No newline at end of file
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 2dbbe3197..407cb4c94 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -17,7 +17,7 @@ from jinja2 import Environment, FileSystemLoader
 
 from sphinx.application import Sphinx
 from sphinx.util.osutil import ensuredir
-from sphinx.websupport.search import search_adapters
+from sphinx.websupport.search import BaseSearch, search_adapters
 from sphinx.websupport import comments as sphinxcomments
 
 class WebSupportApp(Sphinx):
@@ -66,11 +66,14 @@ class WebSupport(object):
         self.template_env = Environment(loader=loader)
 
     def _init_search(self, search):
-        mod, cls = search_adapters[search]
-        search_class = getattr(__import__('sphinx.websupport.search.' + mod, 
+        if isinstance(search, BaseSearch):
+            self.search = search
+        else:
+            mod, cls = search_adapters[search]
+            search_class = getattr(__import__('sphinx.websupport.search.' + mod, 
                                           None, None, [cls]), cls)
-        search_path = path.join(self.outdir, 'search')
-        self.search = search_class(search_path)
+            search_path = path.join(self.outdir, 'search')
+            self.search = search_class(search_path)
         self.results_template = \
             self.template_env.get_template('searchresults.html')
 
@@ -133,7 +136,7 @@ class WebSupport(object):
 
         :param q: the search query
         """
-        results, results_found, results_displayed = self.search.query(q)
+        results = self.search.query(q)
         ctx = {'search_performed': True,
                'search_results': results,
                'q': q}
diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index b4bf73868..1886776a4 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -13,39 +13,107 @@ import re
 
 class BaseSearch(object):
     def init_indexing(self, changed=[]):
+        """Called by the builder to initialize the search indexer. `changed`
+        is a list of pagenames that will be reindexed. You may want to remove
+        these from the search index before indexing begins.
+
+        `param changed` is a list of pagenames that will be re-indexed
+        """
         pass
 
     def finish_indexing(self):
+        """Called by the builder when writing has been completed. Use this
+        to perform any finalization or cleanup actions after indexing is
+        complete.
+        """
         pass
 
     def feed(self, pagename, title, doctree):
+        """Called by the builder to add a doctree to the index. Converts the
+        `doctree` to text and passes it to :meth:`add_document`. You probably
+        won't want to override this unless you need access to the `doctree`. 
+        Override :meth:`add_document` instead.
+
+        `pagename` is the name of the page to be indexed
+
+        `title` is the title of the page to be indexed
+
+        `doctree` is the docutils doctree representation of the page
+        """
         self.add_document(pagename, title, doctree.astext())
 
-    def add_document(self, path, title, text):
-        raise NotImplemented
+    def add_document(self, pagename, title, text):
+        """Called by :meth:`feed` to add a document to the search index.
+        This method should should do everything necessary to add a single
+        document to the search index.
+
+        `pagename` is name of the page being indexed.
+        It is the combination of the source files relative path and filename,
+        minus the extension. For example, if the source file is 
+        "ext/builders.rst", the `pagename` would be "ext/builders". This
+        will need to be returned with search results when processing a 
+        query.
+
+        `title` is the page's title, and will need to be returned with 
+        search results.
+
+        `text` is the full text of the page. You probably want to store this
+        somehow to use while creating the context for search results.
+        """
+        raise NotImplementedError()
 
     def query(self, q):
+        """Called by the web support api to get search results. This method 
+        compiles the regular expression to be used when
+        :meth:`extracting context <extract_context>`, then calls
+        :meth:`handle_query`. You won't want to override this unless you
+        don't want to use the included :meth:`extract_context` method.
+        Override :meth:`handle_query` instead.
+        
+        `q` is the search query string.
+        """
         self.context_re = re.compile('|'.join(q.split()), re.I)
         return self.handle_query(q)
 
     def handle_query(self, q):
-        raise NotImplemented
+        """Called by :meth:`query` to retrieve search results for a search
+        query `q`. This should return an iterable containing tuples of the
+        following format::
 
-    def extract_context(self, text, query_string):
+            (<path>, <title> <context>)
+
+        `path` and `title` are the same values that were passed to
+        :meth:`add_document`, and `context` should be a short text snippet
+        of the text surrounding the search query in the document.
+
+        The :meth:`extract_context` method is provided as a simple way
+        to create the `context`.
+        """
+        raise NotImplementedError()
+
+    def extract_context(self, text, length=240):
+        """Extract the context for the search query from the documents
+        full `text`.
+
+        `text` is the full text of the document to create the context for.
+
+        `length` is the length of the context snippet to return.
+        """
         res = self.context_re.search(text)
         if res is None:
             return ''
-        start = max(res.start() - 120, 0)
-        end = start + 240
-        context = ''.join(['...' if start > 0 else '',
-                           text[start:end],
-                           '...' if end < len(text) else ''])
+        context_start = max(res.start() - length/2, 0)
+        context_end = start + length
+        context = ''.join(['...' if context_start > 0 else '',
+                           text[context_start:context_end],
+                           '...' if context_end < len(text) else ''])
         
         try:
             return unicode(context, errors='ignore')
         except TypeError:
             return context
-    
+
+# The build in search adapters.
 search_adapters = {
     'xapian': ('xapiansearch', 'XapianSearch'),
     'whoosh': ('whooshsearch', 'WhooshSearch'),
diff --git a/sphinx/websupport/search/whooshsearch.py b/sphinx/websupport/search/whooshsearch.py
index 991d42326..00c7403c5 100644
--- a/sphinx/websupport/search/whooshsearch.py
+++ b/sphinx/websupport/search/whooshsearch.py
@@ -38,8 +38,8 @@ class WhooshSearch(BaseSearch):
     def finish_indexing(self):
         self.writer.commit()
        
-    def add_document(self, path, title, text):
-        self.writer.add_document(path=unicode(path),
+    def add_document(self, pagename, title, text):
+        self.writer.add_document(path=unicode(pagename),
                                  title=title, 
                                  text=text)
 
@@ -47,10 +47,10 @@ class WhooshSearch(BaseSearch):
         res = self.searcher.find('text', q)
         results = []
         for result in res:
-            context = self.extract_context(result['text'], q)
+            context = self.extract_context(result['text'])
             
             results.append((result['path'],
                             result.get('title', ''),
                             context))
         
-        return results, len(res), res.scored_length()
+        return results
diff --git a/sphinx/websupport/search/xapiansearch.py b/sphinx/websupport/search/xapiansearch.py
index f8dbecd9c..f5ad9688a 100644
--- a/sphinx/websupport/search/xapiansearch.py
+++ b/sphinx/websupport/search/xapiansearch.py
@@ -70,15 +70,13 @@ class XapianSearch(BaseSearch):
         # Find the top 100 results for the query.
         enquire.set_query(query)
         matches = enquire.get_mset(0, 100)
-        results_found = matches.get_matches_estimated()
-        results_displayed = matches.size()
 
         results = []
 
         for m in matches:
-            context = self.extract_context(m.document.get_data(), q)
+            context = self.extract_context(m.document.get_data())
             results.append((m.document.get_value(self.DOC_PATH),
                             m.document.get_value(self.DOC_TITLE),
                             ''.join(context) ))
 
-        return results, results_found, results_displayed
+        return results

From 1f2a52f45c752d9c843089d9c195aa74b2b47d61 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 13 Jul 2010 17:00:23 -0500
Subject: [PATCH 038/127] small cleanup of xapiansearch.py

---
 sphinx/websupport/search/__init__.py     |  4 ++--
 sphinx/websupport/search/whooshsearch.py | 19 ++++++++++---------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index 1886776a4..e1d7ea471 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -103,11 +103,11 @@ class BaseSearch(object):
         if res is None:
             return ''
         context_start = max(res.start() - length/2, 0)
-        context_end = start + length
+        context_end = context_start + length
         context = ''.join(['...' if context_start > 0 else '',
                            text[context_start:context_end],
                            '...' if context_end < len(text) else ''])
-        
+
         try:
             return unicode(context, errors='ignore')
         except TypeError:
diff --git a/sphinx/websupport/search/whooshsearch.py b/sphinx/websupport/search/whooshsearch.py
index 00c7403c5..52f49d8d9 100644
--- a/sphinx/websupport/search/whooshsearch.py
+++ b/sphinx/websupport/search/whooshsearch.py
@@ -18,6 +18,9 @@ from sphinx.util.osutil import ensuredir
 from sphinx.websupport.search import BaseSearch
 
 class WhooshSearch(BaseSearch):
+    """The whoosh search adapter for sphinx web support."""
+
+    # Define the Whoosh Schema for the search index.
     schema = Schema(path=ID(stored=True, unique=True),
                     title=TEXT(field_boost=2.0, stored=True),
                     text=TEXT(analyzer=StemmingAnalyzer(), stored=True))
@@ -33,24 +36,22 @@ class WhooshSearch(BaseSearch):
     def init_indexing(self, changed=[]):
         for changed_path in changed:
             self.index.delete_by_term('path', changed_path)
-        self.writer = self.index.writer()
+        self.index_writer = self.index.writer()
 
     def finish_indexing(self):
-        self.writer.commit()
+        self.index_writer.commit()
        
     def add_document(self, pagename, title, text):
-        self.writer.add_document(path=unicode(pagename),
-                                 title=title, 
-                                 text=text)
+        self.index_writer.add_document(path=unicode(pagename),
+                                       title=title, 
+                                       text=text)
 
     def handle_query(self, q):
-        res = self.searcher.find('text', q)
+        whoosh_results = self.searcher.find('text', q)
         results = []
-        for result in res:
+        for result in whoosh_results:
             context = self.extract_context(result['text'])
-            
             results.append((result['path'],
                             result.get('title', ''),
                             context))
-        
         return results

From dc2f45208ff306926c99dffa55b78089ef85c476 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 15 Jul 2010 13:25:12 -0500
Subject: [PATCH 039/127] separate sqlalchemystorage from __init__

---
 doc/web/searchadapters.rst                    |  47 +++++++
 doc/web/storagebackends.rst                   |  47 +++++++
 doc/websupport.rst                            |   3 +-
 sphinx/websupport/__init__.py                 |  14 +-
 sphinx/websupport/comments/__init__.py        | 123 +----------------
 .../websupport/comments/sqlalchemystorage.py  | 125 ++++++++++++++++++
 6 files changed, 229 insertions(+), 130 deletions(-)
 create mode 100644 doc/web/searchadapters.rst
 create mode 100644 doc/web/storagebackends.rst
 create mode 100644 sphinx/websupport/comments/sqlalchemystorage.py

diff --git a/doc/web/searchadapters.rst b/doc/web/searchadapters.rst
new file mode 100644
index 000000000..83e928baa
--- /dev/null
+++ b/doc/web/searchadapters.rst
@@ -0,0 +1,47 @@
+.. _searchadapters:
+
+.. currentmodule:: sphinx.websupport.search
+
+Search Adapters
+===============
+
+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::
+
+   support = Websupport(srcdir=srcdir,
+                        outdir=outdir,
+			search=MySearch())
+
+For more information about creating a custom search adapter, please see
+the documentation of the :class:`BaseSearch` class below.
+
+.. class:: BaseSearch
+
+   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
+
diff --git a/doc/web/storagebackends.rst b/doc/web/storagebackends.rst
new file mode 100644
index 000000000..83e928baa
--- /dev/null
+++ b/doc/web/storagebackends.rst
@@ -0,0 +1,47 @@
+.. _searchadapters:
+
+.. currentmodule:: sphinx.websupport.search
+
+Search Adapters
+===============
+
+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::
+
+   support = Websupport(srcdir=srcdir,
+                        outdir=outdir,
+			search=MySearch())
+
+For more information about creating a custom search adapter, please see
+the documentation of the :class:`BaseSearch` class below.
+
+.. class:: BaseSearch
+
+   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
+
diff --git a/doc/websupport.rst b/doc/websupport.rst
index 1b6725df1..c7833e7ab 100644
--- a/doc/websupport.rst
+++ b/doc/websupport.rst
@@ -12,4 +12,5 @@ into your web application. To learn more read the
    web/quickstart
    web/api
    web/frontend
-   web/searchadapters
\ No newline at end of file
+   web/searchadapters
+   web/storagebackends
\ No newline at end of file
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 407cb4c94..c60c93505 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -18,7 +18,7 @@ from jinja2 import Environment, FileSystemLoader
 from sphinx.application import Sphinx
 from sphinx.util.osutil import ensuredir
 from sphinx.websupport.search import BaseSearch, search_adapters
-from sphinx.websupport import comments as sphinxcomments
+from sphinx.websupport.comments import StorageBackend
 
 class WebSupportApp(Sphinx):
     def __init__(self, *args, **kwargs):
@@ -46,17 +46,18 @@ class WebSupport(object):
         self._init_comments(comments)
     
     def _init_comments(self, comments):
-        if isinstance(comments, sphinxcomments.CommentBackend):
+        if isinstance(comments, StorageBackend):
             self.comments = comments
         else:
-            # If a CommentBackend isn't provided, use the default
+            # If a StorageBackend isn't provided, use the default
             # SQLAlchemy backend with an SQLite db.
-            from sphinx.websupport.comments import SQLAlchemyComments
+            from sphinx.websupport.comments.sqlalchemystorage \
+                import SQLAlchemyStorage
             from sqlalchemy import create_engine
             db_path = path.join(self.outdir, 'comments', 'comments.db')
             ensuredir(path.dirname(db_path))
             engine = create_engine('sqlite:///%s' % db_path)
-            self.comments = SQLAlchemyComments(engine)
+            self.comments = SQLAlchemyStorage(engine)
         
     def _init_templating(self):
         import sphinx
@@ -93,8 +94,7 @@ class WebSupport(object):
                             self.outdir, doctreedir, 'websupport',
                             search=self.search,
                             comments=self.comments)
-        # TODO:
-        # Hook comments into Sphinx signals.
+
         self.comments.pre_build()
         app.build()
         self.comments.post_build()
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 395bde580..66b9012af 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -1,12 +1,5 @@
-from datetime import datetime
 
-from sqlalchemy.orm import sessionmaker
-
-from sphinx.websupport.comments.db import Base, Node, Comment, Vote
-
-Session = sessionmaker()
-
-class CommentBackend(object):
+class StorageBackend(object):
     def pre_build(self):
         pass
 
@@ -22,117 +15,3 @@ class CommentBackend(object):
 
     def get_comments(self, parent_id):
         raise NotImplemented
-
-
-class SQLAlchemyComments(CommentBackend):
-    def __init__(self, engine):
-        self.engine = engine
-        Base.metadata.bind = engine
-        Base.metadata.create_all()
-        Session.configure(bind=engine)
-        self.session = Session()
-
-    def pre_build(self):
-        self.current_pk = None
-
-    def add_node(self, document, line, source, treeloc):
-        node = Node(document, line, source, treeloc)
-        self.session.add(node)
-        if self.current_pk is None:
-            self.session.commit()
-            self.current_pk = node.id
-        else:
-            self.current_pk += 1
-        return self.current_pk
-
-    def post_build(self):
-        self.session.commit()
-
-    def add_comment(self, parent_id, text, displayed, 
-                    username, rating, time):
-        time = time or datetime.now()
-
-        id = parent_id[1:]
-        if parent_id[0] == 's':
-            node = self.session.query(Node).filter(Node.id == id).first()
-            comment = Comment(text, displayed, username, rating, 
-                              time, node=node)
-        elif parent_id[0] == 'c':
-            parent = self.session.query(Comment).filter(Comment.id == id).first()
-            comment = Comment(text, displayed, username, rating, 
-                              time, parent=parent)
-            
-        self.session.add(comment)
-        self.session.commit()
-        return self.serializable(comment)
-        
-    def get_comments(self, parent_id, user_id):
-        parent_id = parent_id[1:]
-        node = self.session.query(Node).filter(Node.id == parent_id).first()
-        comments = []
-        for comment in node.comments:
-            comments.append(self.serializable(comment, user_id))
-
-        return comments
-
-    def process_vote(self, comment_id, user_id, value):
-        vote = self.session.query(Vote).filter(
-            Vote.comment_id == comment_id).filter(
-            Vote.user_id == user_id).first()
-        
-        comment = self.session.query(Comment).filter(
-            Comment.id == comment_id).first()
-
-        if vote is None:
-            vote = Vote(comment_id, user_id, value)
-            comment.rating += value
-        else:
-            comment.rating += value - vote.value
-            vote.value = value
-        self.session.add(vote)
-        self.session.commit()
-
-    def serializable(self, comment, user_id=None):
-        delta = datetime.now() - comment.time
-
-        time = {'year': comment.time.year,
-                'month': comment.time.month,
-                'day': comment.time.day,
-                'hour': comment.time.hour,
-                'minute': comment.time.minute,
-                'second': comment.time.second,
-                'iso': comment.time.isoformat(),
-                'delta': self.pretty_delta(delta)}
-
-        vote = ''
-        if user_id is not None:
-            vote = self.session.query(Vote).filter(
-                Vote.comment_id == comment.id).filter(
-                Vote.user_id == user_id).first()
-            if vote is not None:
-                vote = vote.value 
-
-        return {'text': comment.text,
-                'username': comment.username or 'Anonymous',
-                'id': comment.id,
-                'rating': comment.rating,
-                'age': delta.seconds,
-                'time': time,
-                'vote': vote or 0,
-                'node': comment.node.id if comment.node else None,
-                'parent': comment.parent.id if comment.parent else None,
-                'children': [self.serializable(child, user_id) 
-                             for child in comment.children]}
-
-    def pretty_delta(self, delta):
-        days = delta.days
-        seconds = delta.seconds
-        hours = seconds / 3600
-        minutes = seconds / 60
-
-        if days == 0:
-            dt = (minutes, 'minute') if hours == 0 else (hours, 'hour')
-        else:
-            dt = (days, 'day')
-
-        return '%s %s ago' % dt if dt[0] == 1 else '%s %ss ago' % dt
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
new file mode 100644
index 000000000..31403c0ab
--- /dev/null
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -0,0 +1,125 @@
+from datetime import datetime
+
+from sqlalchemy.orm import sessionmaker
+
+from sphinx.websupport.comments import StorageBackend
+from sphinx.websupport.comments.db import Base, Node, Comment, Vote
+
+Session = sessionmaker()
+
+class SQLAlchemyStorage(StorageBackend):
+    def __init__(self, engine):
+        self.engine = engine
+        Base.metadata.bind = engine
+        Base.metadata.create_all()
+        Session.configure(bind=engine)
+
+    def pre_build(self):
+        self.build_session = Session()
+
+    def add_node(self, document, line, source, treeloc):
+        node = Node(document, line, source, treeloc)
+        self.build_session.add(node)
+        self.build_session.flush()
+        return node.id
+
+    def post_build(self):
+        self.build_session.commit()
+        self.build_session.close()
+
+    def add_comment(self, parent_id, text, displayed, 
+                    username, rating, time):
+        time = time or datetime.now()
+        
+        session = Session()
+
+        id = parent_id[1:]
+        if parent_id[0] == 's':
+            node = session.query(Node).filter(Node.id == id).first()
+            comment = Comment(text, displayed, username, rating, 
+                              time, node=node)
+        elif parent_id[0] == 'c':
+            parent = session.query(Comment).filter(Comment.id == id).first()
+            comment = Comment(text, displayed, username, rating, 
+                              time, parent=parent)
+            
+        session.add(comment)
+        session.commit()
+        comment = self.serializable(session, comment)
+        session.close()
+        return comment
+        
+    def get_comments(self, parent_id, user_id):
+        parent_id = parent_id[1:]
+        session = Session()
+        node = session.query(Node).filter(Node.id == parent_id).first()
+        comments = []
+        for comment in node.comments:
+            comments.append(self.serializable(session, comment, user_id))
+
+        session.close()
+        return comments
+
+    def process_vote(self, comment_id, user_id, value):
+        session = Session()
+        vote = session.query(Vote).filter(
+            Vote.comment_id == comment_id).filter(
+            Vote.user_id == user_id).first()
+        
+        comment = session.query(Comment).filter(
+            Comment.id == comment_id).first()
+
+        if vote is None:
+            vote = Vote(comment_id, user_id, value)
+            comment.rating += value
+        else:
+            comment.rating += value - vote.value
+            vote.value = value
+        session.add(vote)
+        session.commit()
+        session.close()
+
+    def serializable(self, session, comment, user_id=None):
+        delta = datetime.now() - comment.time
+
+        time = {'year': comment.time.year,
+                'month': comment.time.month,
+                'day': comment.time.day,
+                'hour': comment.time.hour,
+                'minute': comment.time.minute,
+                'second': comment.time.second,
+                'iso': comment.time.isoformat(),
+                'delta': self.pretty_delta(delta)}
+
+        vote = ''
+        if user_id is not None:
+            vote = session.query(Vote).filter(
+                Vote.comment_id == comment.id).filter(
+                Vote.user_id == user_id).first()
+            if vote is not None:
+                vote = vote.value 
+
+        return {'text': comment.text,
+                'username': comment.username or 'Anonymous',
+                'id': comment.id,
+                'rating': comment.rating,
+                'age': delta.seconds,
+                'time': time,
+                'vote': vote or 0,
+                'node': comment.node.id if comment.node else None,
+                'parent': comment.parent.id if comment.parent else None,
+                'children': [self.serializable(session, child, user_id) 
+                             for child in comment.children]}
+
+    def pretty_delta(self, delta):
+        days = delta.days
+        seconds = delta.seconds
+        hours = seconds / 3600
+        minutes = seconds / 60
+
+        if days == 0:
+            dt = (minutes, 'minute') if hours == 0 else (hours, 'hour')
+        else:
+            dt = (days, 'day')
+
+        return '%s %s ago' % dt if dt[0] == 1 else '%s %ss ago' % dt

From dc4000f4af30a37b2e17f115a1a2e1fb079c70ba Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 16 Jul 2010 13:31:16 -0500
Subject: [PATCH 040/127] More docs

---
 doc/web/storagebackends.rst                   | 50 ++++---------------
 sphinx/websupport/comments/__init__.py        | 18 +++++++
 .../websupport/comments/sqlalchemystorage.py  |  2 +
 3 files changed, 31 insertions(+), 39 deletions(-)

diff --git a/doc/web/storagebackends.rst b/doc/web/storagebackends.rst
index 83e928baa..87e1b478a 100644
--- a/doc/web/storagebackends.rst
+++ b/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
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 66b9012af..20d923860 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/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
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 31403c0ab..3d4672bf0 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/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()

From decffe66111e92afcc60a49e4014ffc8980d4300 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 19 Jul 2010 11:37:17 -0500
Subject: [PATCH 041/127] remove whitespace

---
 sphinx/websupport/comments/sqlalchemystorage.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 3d4672bf0..a14ef476f 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -32,8 +32,6 @@ class SQLAlchemyStorage(StorageBackend):
         time = time or datetime.now()
         
         session = Session()
-
-        
         
         id = parent_id[1:]
         if parent_id[0] == 's':

From 90eb73e7b7c087de3c727ba71bdd2de7a58250de Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 19 Jul 2010 14:12:15 -0500
Subject: [PATCH 042/127] started proposal backend

---
 sphinx/websupport/__init__.py                 | 36 ++++++++++-------
 sphinx/websupport/comments/__init__.py        | 16 ++++++--
 sphinx/websupport/comments/db.py              | 23 ++++++++++-
 .../websupport/comments/sqlalchemystorage.py  | 39 +++++++++++++++----
 sphinx/writers/websupport.py                  | 10 ++---
 5 files changed, 93 insertions(+), 31 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index c60c93505..7c39681ad 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -23,7 +23,7 @@ from sphinx.websupport.comments import StorageBackend
 class WebSupportApp(Sphinx):
     def __init__(self, *args, **kwargs):
         self.search = kwargs.pop('search', None)
-        self.comments = kwargs.pop('comments', None)
+        self.storage = kwargs.pop('storage', None)
         Sphinx.__init__(self, *args, **kwargs)
 
 class WebSupport(object):
@@ -32,7 +32,7 @@ class WebSupport(object):
     """
 
     def __init__(self, srcdir='', outdir='', datadir='', search=None,
-                 comments=None):
+                 storage=None):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
@@ -43,21 +43,21 @@ class WebSupport(object):
         if search is not None:
             self._init_search(search)
 
-        self._init_comments(comments)
+        self._init_storage(storage)
     
-    def _init_comments(self, comments):
-        if isinstance(comments, StorageBackend):
-            self.comments = comments
+    def _init_storage(self, storage):
+        if isinstance(storage, StorageBackend):
+            self.storage = storage
         else:
             # If a StorageBackend isn't provided, use the default
             # SQLAlchemy backend with an SQLite db.
             from sphinx.websupport.comments.sqlalchemystorage \
                 import SQLAlchemyStorage
             from sqlalchemy import create_engine
-            db_path = path.join(self.outdir, 'comments', 'comments.db')
+            db_path = path.join(self.outdir, 'db', 'websupport.db')
             ensuredir(path.dirname(db_path))
             engine = create_engine('sqlite:///%s' % db_path)
-            self.comments = SQLAlchemyStorage(engine)
+            self.storage = SQLAlchemyStorage(engine)
         
     def _init_templating(self):
         import sphinx
@@ -93,11 +93,11 @@ class WebSupport(object):
         app = WebSupportApp(self.srcdir, self.srcdir,
                             self.outdir, doctreedir, 'websupport',
                             search=self.search,
-                            comments=self.comments)
+                            storage=self.storage)
 
-        self.comments.pre_build()
+        self.storage.pre_build()
         app.build()
-        self.comments.post_build()
+        self.storage.post_build()
 
     def get_document(self, docname):
         """Load and return a document from a pickle. The document will
@@ -178,7 +178,7 @@ class WebSupport(object):
         :param node_id: the id of the node to get comments for.
         :param user_id: the id of the user viewing the comments.
         """
-        return self.comments.get_comments(node_id, user_id)
+        return self.storage.get_comments(node_id, user_id)
 
     def add_comment(self, parent_id, text, displayed=True, username=None,
                     rating=0, time=None):
@@ -202,9 +202,17 @@ class WebSupport(object):
         :param rating: the starting rating of the comment, defaults to 0.
         :param time: the time the comment was created, defaults to now.
         """
-        return self.comments.add_comment(parent_id, text, displayed, 
+        return self.storage.add_comment(parent_id, text, displayed, 
                                          username, rating, time)
     
+    def get_proposals(self, node_id, user_id=None):
+        return self.storage.get_proposals(node_id, user_id)
+
+    def add_proposal(self, parent_id, text, displayed=True, username=None,
+                    rating=0, time=None):
+        return self.storage.add_proposal(parent_id, text, displayed, 
+                                          username, rating, time)
+
     def process_vote(self, comment_id, user_id, value):
         """Process a user's vote. The web support package relies
         on the API user to perform authentication. The API user will 
@@ -230,4 +238,4 @@ class WebSupport(object):
         :param value: 1 for an upvote, -1 for a downvote, 0 for an unvote.
         """
         value = int(value)
-        self.comments.process_vote(comment_id, user_id, value)
+        self.storage.process_vote(comment_id, user_id, value)
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 20d923860..a78a19c16 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -17,7 +17,7 @@ class StorageBackend(object):
         
         `treeloc` is for future use.
         """
-        raise NotImplemented
+        raise NotImplementedError()
     
     def post_build(self):
         """Called after a build has completed. Use this to finalize the
@@ -28,8 +28,18 @@ class StorageBackend(object):
     def add_comment(self, parent_id, text, displayed, username, 
                     rating, time):
         """Called when a comment is being added."""
-        raise NotImplemented
+        raise NotImplementedError()
 
     def get_comments(self, parent_id):
         """Called to retrieve all comments for a node."""
-        raise NotImplemented
+        raise NotImplementedError()
+
+    def add_proposal(self, parent_id, text, displayed, username, 
+                    rating, time):
+        raise NotImplementedError()
+
+    def get_proposals(self, parent_id):
+        raise NotImplementedError()
+
+    def process_vote(self, comment_id, user_id, value):
+        raise NotImplementedError()
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 22020b4b5..1b3cd9d8b 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -50,7 +50,7 @@ class Comment(Base):
         self.node = node
         self.parent = parent
 
-class Vote(Base):
+class CommentVote(Base):
     __tablename__ = db_prefix + 'vote'
 
     id = Column(Integer, primary_key=True)
@@ -68,4 +68,25 @@ class Vote(Base):
         self.value = value
         self.user_id = user_id
         self.comment_id = comment_id
+
+class Proposal(Base):
+    __tablename__ = db_prefix + 'proposals'
+
+    id = Column(Integer, primary_key=True)
+    rating = Column(Integer, nullable=False)
+    time = Column(DateTime, nullable=False)
+    text = Column(Text, nullable=False)
+    displayed = Column(Boolean, index=True, default=False)
+    username = Column(String(64))
+
+    node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
+    node = relation(Node, backref='proposals')
+
+    def __init__(self, text, displayed, username, rating, time, node):
+        self.text = text
+        self.displayed = displayed
+        self.username = username
+        self.rating = rating
+        self.time = time
+        self.node = node
     
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index a14ef476f..26f352ac5 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -3,7 +3,7 @@ from datetime import datetime
 from sqlalchemy.orm import sessionmaker
 
 from sphinx.websupport.comments import StorageBackend
-from sphinx.websupport.comments.db import Base, Node, Comment, Vote
+from sphinx.websupport.comments.db import Base, Node, Comment, CommentVote
 
 Session = sessionmaker()
 
@@ -60,17 +60,40 @@ class SQLAlchemyStorage(StorageBackend):
         session.close()
         return comments
 
+    def add_proposal(self, parent_id, text, displayed, username, 
+                    rating, time):
+        time = time or datetime.now()
+        
+        session = Session()
+        
+        node = session.query(Node).filter(Node.id == parent_id).first()
+        proposal= Proposal(text, displayed, username, rating, time, node)
+            
+        session.add(proposal)
+        session.commit()
+        session.close()
+        return proposal
+
+    def get_proposals(self, parent_id):
+        session = Session()
+        node = session.query(Node).filter(Node.id == parent_id).first()
+        proposals = []
+
+        # TODO
+
+        return proposals
+
     def process_vote(self, comment_id, user_id, value):
         session = Session()
-        vote = session.query(Vote).filter(
-            Vote.comment_id == comment_id).filter(
-            Vote.user_id == user_id).first()
+        vote = session.query(CommentVote).filter(
+            CommentVote.comment_id == comment_id).filter(
+            CommentVote.user_id == user_id).first()
         
         comment = session.query(Comment).filter(
             Comment.id == comment_id).first()
 
         if vote is None:
-            vote = Vote(comment_id, user_id, value)
+            vote = CommentVote(comment_id, user_id, value)
             comment.rating += value
         else:
             comment.rating += value - vote.value
@@ -93,9 +116,9 @@ class SQLAlchemyStorage(StorageBackend):
 
         vote = ''
         if user_id is not None:
-            vote = session.query(Vote).filter(
-                Vote.comment_id == comment.id).filter(
-                Vote.user_id == user_id).first()
+            vote = session.query(CommentVote).filter(
+                CommentVote.comment_id == comment.id).filter(
+                CommentVote.user_id == user_id).first()
             if vote is not None:
                 vote = vote.value 
 
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 18c0807d6..04c989b22 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -57,9 +57,9 @@ class WebSupportTranslator(HTMLTranslator):
             self.in_commentable = False
 
     def add_db_node(self, node):
-        comments = self.builder.app.comments
-        db_node_id = comments.add_node(document=self.builder.cur_docname,
-                                       line=node.line,
-                                       source=node.rawsource,
-                                       treeloc='???')
+        storage = self.builder.app.storage
+        db_node_id = storage.add_node(document=self.builder.cur_docname,
+                                      line=node.line,
+                                      source=node.rawsource,
+                                      treeloc='???')
         return db_node_id

From 061db6cb22e1a7f24281c17bb77a8bd69e7d3f73 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 19 Jul 2010 14:53:37 -0500
Subject: [PATCH 043/127] moved serializable() to db.Comment

---
 sphinx/websupport/comments/db.py              | 54 ++++++++++++++++++-
 .../websupport/comments/sqlalchemystorage.py  | 54 ++-----------------
 2 files changed, 55 insertions(+), 53 deletions(-)

diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 1b3cd9d8b..9d0fc2a2f 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -1,11 +1,15 @@
+from datetime import datetime
+
 from sqlalchemy import Column, Integer, Text, String, Boolean, ForeignKey,\
 DateTime
 from sqlalchemy.schema import UniqueConstraint
 from sqlalchemy.ext.declarative import declarative_base
-from sqlalchemy.orm import relation
+from sqlalchemy.orm import relation, sessionmaker
 
 Base = declarative_base()
 
+Session = sessionmaker()
+
 db_prefix = 'sphinx_'
 
 class Node(Base):
@@ -50,8 +54,54 @@ class Comment(Base):
         self.node = node
         self.parent = parent
 
+    def serializable(self, user_id=None):
+        delta = datetime.now() - self.time
+
+        time = {'year': self.time.year,
+                'month': self.time.month,
+                'day': self.time.day,
+                'hour': self.time.hour,
+                'minute': self.time.minute,
+                'second': self.time.second,
+                'iso': self.time.isoformat(),
+                'delta': self.pretty_delta(delta)}
+
+        vote = ''
+        if user_id is not None:
+            session = Session()
+            vote = session.query(CommentVote).filter(
+                CommentVote.comment_id == self.id).filter(
+                CommentVote.user_id == user_id).first()
+            vote = vote.value if vote is not None else 0
+            session.close()
+
+        return {'text': self.text,
+                'username': self.username or 'Anonymous',
+                'id': self.id,
+                'rating': self.rating,
+                'age': delta.seconds,
+                'time': time,
+                'vote': vote or 0,
+                'node': self.node.id if self.node else None,
+                'parent': self.parent.id if self.parent else None,
+                'children': [child.serializable(user_id) 
+                             for child in self.children]}
+
+    def pretty_delta(self, delta):
+        days = delta.days
+        seconds = delta.seconds
+        hours = seconds / 3600
+        minutes = seconds / 60
+
+        if days == 0:
+            dt = (minutes, 'minute') if hours == 0 else (hours, 'hour')
+        else:
+            dt = (days, 'day')
+
+        return '%s %s ago' % dt if dt[0] == 1 else '%s %ss ago' % dt
+    
 class CommentVote(Base):
-    __tablename__ = db_prefix + 'vote'
+    __tablename__ = db_prefix + 'commentvote'
 
     id = Column(Integer, primary_key=True)
     # -1 if downvoted, +1 if upvoted, 0 if voted then unvoted.
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 26f352ac5..10f1fa3cc 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -1,11 +1,7 @@
 from datetime import datetime
 
-from sqlalchemy.orm import sessionmaker
-
 from sphinx.websupport.comments import StorageBackend
-from sphinx.websupport.comments.db import Base, Node, Comment, CommentVote
-
-Session = sessionmaker()
+from sphinx.websupport.comments.db import Base, Node, Comment, CommentVote, Session
 
 class SQLAlchemyStorage(StorageBackend):
     def __init__(self, engine):
@@ -45,7 +41,7 @@ class SQLAlchemyStorage(StorageBackend):
             
         session.add(comment)
         session.commit()
-        comment = self.serializable(session, comment)
+        comment = comment.serializable()
         session.close()
         return comment
         
@@ -55,7 +51,7 @@ class SQLAlchemyStorage(StorageBackend):
         node = session.query(Node).filter(Node.id == parent_id).first()
         comments = []
         for comment in node.comments:
-            comments.append(self.serializable(session, comment, user_id))
+            comments.append(comment.serializable(user_id))
 
         session.close()
         return comments
@@ -102,47 +98,3 @@ class SQLAlchemyStorage(StorageBackend):
         session.commit()
         session.close()
 
-    def serializable(self, session, comment, user_id=None):
-        delta = datetime.now() - comment.time
-
-        time = {'year': comment.time.year,
-                'month': comment.time.month,
-                'day': comment.time.day,
-                'hour': comment.time.hour,
-                'minute': comment.time.minute,
-                'second': comment.time.second,
-                'iso': comment.time.isoformat(),
-                'delta': self.pretty_delta(delta)}
-
-        vote = ''
-        if user_id is not None:
-            vote = session.query(CommentVote).filter(
-                CommentVote.comment_id == comment.id).filter(
-                CommentVote.user_id == user_id).first()
-            if vote is not None:
-                vote = vote.value 
-
-        return {'text': comment.text,
-                'username': comment.username or 'Anonymous',
-                'id': comment.id,
-                'rating': comment.rating,
-                'age': delta.seconds,
-                'time': time,
-                'vote': vote or 0,
-                'node': comment.node.id if comment.node else None,
-                'parent': comment.parent.id if comment.parent else None,
-                'children': [self.serializable(session, child, user_id) 
-                             for child in comment.children]}
-
-    def pretty_delta(self, delta):
-        days = delta.days
-        seconds = delta.seconds
-        hours = seconds / 3600
-        minutes = seconds / 60
-
-        if days == 0:
-            dt = (minutes, 'minute') if hours == 0 else (hours, 'hour')
-        else:
-            dt = (days, 'day')
-
-        return '%s %s ago' % dt if dt[0] == 1 else '%s %ss ago' % dt

From 8c188370f293bc248c1d1f60417c8538479e53d9 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 19 Jul 2010 14:58:06 -0500
Subject: [PATCH 044/127] use composite pk for db.CommentVote

---
 sphinx/websupport/comments/db.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 9d0fc2a2f..4cf8878f2 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -103,13 +103,12 @@ class Comment(Base):
 class CommentVote(Base):
     __tablename__ = db_prefix + 'commentvote'
 
-    id = Column(Integer, primary_key=True)
+    user_id = Column(Integer, primary_key=True)
     # -1 if downvoted, +1 if upvoted, 0 if voted then unvoted.
     value = Column(Integer, nullable=False)
-    user_id = Column(Integer, index=True, nullable=False)
 
     comment_id = Column(Integer, ForeignKey(db_prefix + 'comments.id'),
-                        nullable=False)
+                        primary_key=True)
     comment = relation(Comment, backref="votes")
 
     __table_args__ = (UniqueConstraint(comment_id, user_id), {}) 

From 19042aaf94a2b08deee436455fcc7b1a78d15516 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 19 Jul 2010 15:14:02 -0500
Subject: [PATCH 045/127] add ProposalVote table to db

---
 sphinx/websupport/comments/db.py | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 4cf8878f2..31f4ff774 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -111,8 +111,6 @@ class CommentVote(Base):
                         primary_key=True)
     comment = relation(Comment, backref="votes")
 
-    __table_args__ = (UniqueConstraint(comment_id, user_id), {}) 
-
     def __init__(self, comment_id, user_id, value):
         self.value = value
         self.user_id = user_id
@@ -139,3 +137,19 @@ class Proposal(Base):
         self.time = time
         self.node = node
     
+class ProposalVote(Base):
+    __tablename__ = db_prefix + 'proposalvote'
+
+    user_id = Column(Integer, primary_key=True)
+    # -1 if downvoted, +1 if upvoted, 0 if voted then unvoted.
+    value = Column(Integer, nullable=False)
+
+    proposal_id = Column(Integer, ForeignKey(db_prefix + 'proposals.id'),
+                         primary_key=True)
+    proposal = relation(Proposal, backref="votes")
+
+    def __init__(self, proposal_id, user_id, value):
+        self.value = value
+        self.user_id = user_id
+        self.proposal_id = proposal_id
+

From 022b229c36a1f46a5eabc9a6cb6465c8e490e88f Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 22 Jul 2010 16:42:29 -0500
Subject: [PATCH 046/127] Unification of Comments and Proposals.

---
 sphinx/websupport/comments/db.py | 42 +++-----------------------------
 1 file changed, 3 insertions(+), 39 deletions(-)

diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 31f4ff774..3a33cb266 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -37,6 +37,7 @@ class Comment(Base):
     text = Column(Text, nullable=False)
     displayed = Column(Boolean, index=True, default=False)
     username = Column(String(64))
+    proposal = Column(Text)
 
     node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
     node = relation(Node, backref='comments')
@@ -45,7 +46,7 @@ class Comment(Base):
     parent = relation('Comment', backref='children', remote_side=[id])
 
     def __init__(self, text, displayed, username, rating, time, 
-                 node=None, parent=None):
+                 node=None, parent=None, proposal=None):
         self.text = text
         self.displayed = displayed
         self.username = username
@@ -53,6 +54,7 @@ class Comment(Base):
         self.time = time
         self.node = node
         self.parent = parent
+        self.proposal = proposal
 
     def serializable(self, user_id=None):
         delta = datetime.now() - self.time
@@ -115,41 +117,3 @@ class CommentVote(Base):
         self.value = value
         self.user_id = user_id
         self.comment_id = comment_id
-
-class Proposal(Base):
-    __tablename__ = db_prefix + 'proposals'
-
-    id = Column(Integer, primary_key=True)
-    rating = Column(Integer, nullable=False)
-    time = Column(DateTime, nullable=False)
-    text = Column(Text, nullable=False)
-    displayed = Column(Boolean, index=True, default=False)
-    username = Column(String(64))
-
-    node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
-    node = relation(Node, backref='proposals')
-
-    def __init__(self, text, displayed, username, rating, time, node):
-        self.text = text
-        self.displayed = displayed
-        self.username = username
-        self.rating = rating
-        self.time = time
-        self.node = node
-    
-class ProposalVote(Base):
-    __tablename__ = db_prefix + 'proposalvote'
-
-    user_id = Column(Integer, primary_key=True)
-    # -1 if downvoted, +1 if upvoted, 0 if voted then unvoted.
-    value = Column(Integer, nullable=False)
-
-    proposal_id = Column(Integer, ForeignKey(db_prefix + 'proposals.id'),
-                         primary_key=True)
-    proposal = relation(Proposal, backref="votes")
-
-    def __init__(self, proposal_id, user_id, value):
-        self.value = value
-        self.user_id = user_id
-        self.proposal_id = proposal_id
-

From d7183639086ceb5511a2446e93535de501e5e370 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Sun, 25 Jul 2010 19:50:20 +0200
Subject: [PATCH 047/127] Remove trailing whitespace

---
 sphinx/websupport/__init__.py                 | 12 ++++-----
 sphinx/websupport/comments/__init__.py        |  6 ++---
 sphinx/websupport/comments/db.py              | 12 ++++-----
 .../websupport/comments/sqlalchemystorage.py  | 25 +++++++++----------
 sphinx/websupport/search/whooshsearch.py      |  4 +--
 sphinx/websupport/search/xapiansearch.py      |  2 +-
 6 files changed, 30 insertions(+), 31 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 7c39681ad..ddaac1f3b 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -44,7 +44,7 @@ class WebSupport(object):
             self._init_search(search)
 
         self._init_storage(storage)
-    
+
     def _init_storage(self, storage):
         if isinstance(storage, StorageBackend):
             self.storage = storage
@@ -58,7 +58,7 @@ class WebSupport(object):
             ensuredir(path.dirname(db_path))
             engine = create_engine('sqlite:///%s' % db_path)
             self.storage = SQLAlchemyStorage(engine)
-        
+
     def _init_templating(self):
         import sphinx
         template_path = path.join(path.dirname(sphinx.__file__),
@@ -71,7 +71,7 @@ class WebSupport(object):
             self.search = search
         else:
             mod, cls = search_adapters[search]
-            search_class = getattr(__import__('sphinx.websupport.search.' + mod, 
+            search_class = getattr(__import__('sphinx.websupport.search.' + mod,
                                           None, None, [cls]), cls)
             search_path = path.join(self.outdir, 'search')
             self.search = search_class(search_path)
@@ -202,15 +202,15 @@ class WebSupport(object):
         :param rating: the starting rating of the comment, defaults to 0.
         :param time: the time the comment was created, defaults to now.
         """
-        return self.storage.add_comment(parent_id, text, displayed, 
+        return self.storage.add_comment(parent_id, text, displayed,
                                          username, rating, time)
-    
+
     def get_proposals(self, node_id, user_id=None):
         return self.storage.get_proposals(node_id, user_id)
 
     def add_proposal(self, parent_id, text, displayed=True, username=None,
                     rating=0, time=None):
-        return self.storage.add_proposal(parent_id, text, displayed, 
+        return self.storage.add_proposal(parent_id, text, displayed,
                                           username, rating, time)
 
     def process_vote(self, comment_id, user_id, value):
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index a78a19c16..aca2ac351 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -18,14 +18,14 @@ class StorageBackend(object):
         `treeloc` is for future use.
         """
         raise NotImplementedError()
-    
+
     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, 
+    def add_comment(self, parent_id, text, displayed, username,
                     rating, time):
         """Called when a comment is being added."""
         raise NotImplementedError()
@@ -34,7 +34,7 @@ class StorageBackend(object):
         """Called to retrieve all comments for a node."""
         raise NotImplementedError()
 
-    def add_proposal(self, parent_id, text, displayed, username, 
+    def add_proposal(self, parent_id, text, displayed, username,
                     rating, time):
         raise NotImplementedError()
 
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 31f4ff774..35f25a2bb 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -15,13 +15,13 @@ db_prefix = 'sphinx_'
 class Node(Base):
     """Data about a Node in a doctree."""
     __tablename__ = db_prefix + 'nodes'
-    
+
     id = Column(Integer, primary_key=True)
     document = Column(String(256), nullable=False)
     line = Column(Integer)
     source = Column(Text, nullable=False)
     treeloc = Column(String(32), nullable=False)
-    
+
     def __init__(self, document, line, source, treeloc):
         self.document = document
         self.line = line
@@ -44,7 +44,7 @@ class Comment(Base):
     parent_id = Column(Integer, ForeignKey(db_prefix + 'comments.id'))
     parent = relation('Comment', backref='children', remote_side=[id])
 
-    def __init__(self, text, displayed, username, rating, time, 
+    def __init__(self, text, displayed, username, rating, time,
                  node=None, parent=None):
         self.text = text
         self.displayed = displayed
@@ -84,7 +84,7 @@ class Comment(Base):
                 'vote': vote or 0,
                 'node': self.node.id if self.node else None,
                 'parent': self.parent.id if self.parent else None,
-                'children': [child.serializable(user_id) 
+                'children': [child.serializable(user_id)
                              for child in self.children]}
 
     def pretty_delta(self, delta):
@@ -99,7 +99,7 @@ class Comment(Base):
             dt = (days, 'day')
 
         return '%s %s ago' % dt if dt[0] == 1 else '%s %ss ago' % dt
-    
+
 class CommentVote(Base):
     __tablename__ = db_prefix + 'commentvote'
 
@@ -136,7 +136,7 @@ class Proposal(Base):
         self.rating = rating
         self.time = time
         self.node = node
-    
+
 class ProposalVote(Base):
     __tablename__ = db_prefix + 'proposalvote'
 
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 10f1fa3cc..c57bee636 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -23,28 +23,28 @@ class SQLAlchemyStorage(StorageBackend):
         self.build_session.commit()
         self.build_session.close()
 
-    def add_comment(self, parent_id, text, displayed, 
+    def add_comment(self, parent_id, text, displayed,
                     username, rating, time):
         time = time or datetime.now()
-        
+
         session = Session()
-        
+
         id = parent_id[1:]
         if parent_id[0] == 's':
             node = session.query(Node).filter(Node.id == id).first()
-            comment = Comment(text, displayed, username, rating, 
+            comment = Comment(text, displayed, username, rating,
                               time, node=node)
         elif parent_id[0] == 'c':
             parent = session.query(Comment).filter(Comment.id == id).first()
-            comment = Comment(text, displayed, username, rating, 
+            comment = Comment(text, displayed, username, rating,
                               time, parent=parent)
-            
+
         session.add(comment)
         session.commit()
         comment = comment.serializable()
         session.close()
         return comment
-        
+
     def get_comments(self, parent_id, user_id):
         parent_id = parent_id[1:]
         session = Session()
@@ -56,15 +56,15 @@ class SQLAlchemyStorage(StorageBackend):
         session.close()
         return comments
 
-    def add_proposal(self, parent_id, text, displayed, username, 
+    def add_proposal(self, parent_id, text, displayed, username,
                     rating, time):
         time = time or datetime.now()
-        
+
         session = Session()
-        
+
         node = session.query(Node).filter(Node.id == parent_id).first()
         proposal= Proposal(text, displayed, username, rating, time, node)
-            
+
         session.add(proposal)
         session.commit()
         session.close()
@@ -84,7 +84,7 @@ class SQLAlchemyStorage(StorageBackend):
         vote = session.query(CommentVote).filter(
             CommentVote.comment_id == comment_id).filter(
             CommentVote.user_id == user_id).first()
-        
+
         comment = session.query(Comment).filter(
             Comment.id == comment_id).first()
 
@@ -97,4 +97,3 @@ class SQLAlchemyStorage(StorageBackend):
         session.add(vote)
         session.commit()
         session.close()
-
diff --git a/sphinx/websupport/search/whooshsearch.py b/sphinx/websupport/search/whooshsearch.py
index 52f49d8d9..658b764dd 100644
--- a/sphinx/websupport/search/whooshsearch.py
+++ b/sphinx/websupport/search/whooshsearch.py
@@ -40,10 +40,10 @@ class WhooshSearch(BaseSearch):
 
     def finish_indexing(self):
         self.index_writer.commit()
-       
+
     def add_document(self, pagename, title, text):
         self.index_writer.add_document(path=unicode(pagename),
-                                       title=title, 
+                                       title=title,
                                        text=text)
 
     def handle_query(self, q):
diff --git a/sphinx/websupport/search/xapiansearch.py b/sphinx/websupport/search/xapiansearch.py
index f5ad9688a..2f2ffbe59 100644
--- a/sphinx/websupport/search/xapiansearch.py
+++ b/sphinx/websupport/search/xapiansearch.py
@@ -37,7 +37,7 @@ class XapianSearch(BaseSearch):
     def finish_indexing(self):
         # Ensure the db lock is removed.
         del self.database
-       
+
     def add_document(self, path, title, text):
         self.database.begin_transaction()
         # sphinx_page_path is used to easily retrieve documents by path.

From 0672a8e379c711a63348af9b57a6a4a92938cb95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Sun, 25 Jul 2010 19:53:57 +0200
Subject: [PATCH 048/127] Fixed line length and indentation of imports

---
 sphinx/websupport/comments/db.py                | 2 +-
 sphinx/websupport/comments/sqlalchemystorage.py | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 35f25a2bb..b73d6a5ae 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -1,7 +1,7 @@
 from datetime import datetime
 
 from sqlalchemy import Column, Integer, Text, String, Boolean, ForeignKey,\
-DateTime
+                       DateTime
 from sqlalchemy.schema import UniqueConstraint
 from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import relation, sessionmaker
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index c57bee636..8ee117502 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -1,7 +1,8 @@
 from datetime import datetime
 
 from sphinx.websupport.comments import StorageBackend
-from sphinx.websupport.comments.db import Base, Node, Comment, CommentVote, Session
+from sphinx.websupport.comments.db import Base, Node, Comment, CommentVote,\
+                                          Session
 
 class SQLAlchemyStorage(StorageBackend):
     def __init__(self, engine):

From 6a4ec66967de0f25e03a73d43e4c57b7295f561c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Sun, 25 Jul 2010 20:03:28 +0200
Subject: [PATCH 049/127] Added missing module docstrings

---
 sphinx/websupport/comments/__init__.py          | 10 ++++++++++
 sphinx/websupport/comments/db.py                | 13 ++++++++++++-
 sphinx/websupport/comments/sqlalchemystorage.py | 11 +++++++++++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index aca2ac351..1f1605184 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -1,3 +1,13 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.comments
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Comments for the websupport package.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
 
 class StorageBackend(object):
     def pre_build(self):
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index b73d6a5ae..db9ab7a80 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -1,3 +1,15 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.comments.db
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    SQLAlchemy table and mapper definitions used by the
+    :class:`sphinx.websupport.comments.SQLAlchemyStorage`.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
 from datetime import datetime
 
 from sqlalchemy import Column, Integer, Text, String, Boolean, ForeignKey,\
@@ -152,4 +164,3 @@ class ProposalVote(Base):
         self.value = value
         self.user_id = user_id
         self.proposal_id = proposal_id
-
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 8ee117502..312663c81 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -1,3 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.comments.sqlalchemystorage
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    A SQLAlchemy storage backend.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
 from datetime import datetime
 
 from sphinx.websupport.comments import StorageBackend

From 1a9a9972911695ae4f64e7c6fccd686f814659bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Sun, 25 Jul 2010 20:45:24 +0200
Subject: [PATCH 050/127] Removed trailing whitespace

---
 sphinx/writers/websupport.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 04c989b22..63281f182 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -25,7 +25,7 @@ class WebSupportTranslator(HTMLTranslator):
     def init_support(self):
         self.in_commentable = False
         self.current_id = 0
-        
+
     def dispatch_visit(self, node):
         if node.__class__.__name__ in self.commentable_nodes:
             self.handle_visit_commentable(node)

From 6d4bd91c837b4bc29455b65f26fb518367a76401 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Sun, 25 Jul 2010 23:03:14 +0200
Subject: [PATCH 051/127] Remove trailing whitespace

---
 sphinx/builders/websupport.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index e2caeccd1..40901eef9 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -25,7 +25,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
 
     def init_translator_class(self):
         self.translator_class = WebSupportTranslator
-        
+
     def write_doc(self, docname, doctree):
         # The translator needs the docname to generate ids.
         self.cur_docname = docname

From 3a32d12bf89b6513ef5fc16d5636340a2fadd343 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sun, 25 Jul 2010 22:37:53 -0500
Subject: [PATCH 052/127] Save proposed changes

---
 sphinx/websupport/__init__.py                 | 13 ++++---
 sphinx/websupport/comments/__init__.py        | 11 +-----
 sphinx/websupport/comments/db.py              |  2 +-
 .../websupport/comments/sqlalchemystorage.py  | 38 ++++---------------
 4 files changed, 17 insertions(+), 47 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 7c39681ad..452dc2950 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -146,10 +146,11 @@ class WebSupport(object):
         return document
 
     def get_comments(self, node_id, user_id=None):
-        """Get the comments associated with `node_id`. If `user_id` is
-        given vote information will be included with the returned comments.
-        The default CommentBackend returns a list of dicts. Each dict
-        represents a comment, and has the following items:
+        """Get the comments and source associated with `node_id`. If 
+        `user_id` is given vote information will be included with the 
+        returned comments. The default CommentBackend returns dict with
+        two keys, *source*, and *comments*. *comments* is a list of
+        dicts that represent a comment, each having the following items:
 
         ============ ======================================================
         Key          Contents
@@ -181,7 +182,7 @@ class WebSupport(object):
         return self.storage.get_comments(node_id, user_id)
 
     def add_comment(self, parent_id, text, displayed=True, username=None,
-                    rating=0, time=None):
+                    rating=0, time=None, proposal=None):
         """Add a comment to a node or another comment. `parent_id` will have
         a one letter prefix, distinguishing between node parents and 
         comment parents, 'c' and 's' respectively. This function will
@@ -203,7 +204,7 @@ class WebSupport(object):
         :param time: the time the comment was created, defaults to now.
         """
         return self.storage.add_comment(parent_id, text, displayed, 
-                                         username, rating, time)
+                                         username, rating, time, proposal)
     
     def get_proposals(self, node_id, user_id=None):
         return self.storage.get_proposals(node_id, user_id)
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index a78a19c16..8cd3c36c4 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -25,8 +25,8 @@ class StorageBackend(object):
         """
         pass
 
-    def add_comment(self, parent_id, text, displayed, username, 
-                    rating, time):
+    def add_comment(self, parent_id, text, displayed, 
+                    username, rating, time, proposal):
         """Called when a comment is being added."""
         raise NotImplementedError()
 
@@ -34,12 +34,5 @@ class StorageBackend(object):
         """Called to retrieve all comments for a node."""
         raise NotImplementedError()
 
-    def add_proposal(self, parent_id, text, displayed, username, 
-                    rating, time):
-        raise NotImplementedError()
-
-    def get_proposals(self, parent_id):
-        raise NotImplementedError()
-
     def process_vote(self, comment_id, user_id, value):
         raise NotImplementedError()
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 3a33cb266..3679e3d6d 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -46,7 +46,7 @@ class Comment(Base):
     parent = relation('Comment', backref='children', remote_side=[id])
 
     def __init__(self, text, displayed, username, rating, time, 
-                 node=None, parent=None, proposal=None):
+                 proposal, node=None, parent=None):
         self.text = text
         self.displayed = displayed
         self.username = username
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 10f1fa3cc..706ea4c03 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -24,7 +24,7 @@ class SQLAlchemyStorage(StorageBackend):
         self.build_session.close()
 
     def add_comment(self, parent_id, text, displayed, 
-                    username, rating, time):
+                    username, rating, time, proposal):
         time = time or datetime.now()
         
         session = Session()
@@ -33,11 +33,11 @@ class SQLAlchemyStorage(StorageBackend):
         if parent_id[0] == 's':
             node = session.query(Node).filter(Node.id == id).first()
             comment = Comment(text, displayed, username, rating, 
-                              time, node=node)
+                              time, proposal, node=node)
         elif parent_id[0] == 'c':
             parent = session.query(Comment).filter(Comment.id == id).first()
             comment = Comment(text, displayed, username, rating, 
-                              time, parent=parent)
+                              time,proposal, parent=parent)
             
         session.add(comment)
         session.commit()
@@ -49,35 +49,11 @@ class SQLAlchemyStorage(StorageBackend):
         parent_id = parent_id[1:]
         session = Session()
         node = session.query(Node).filter(Node.id == parent_id).first()
-        comments = []
-        for comment in node.comments:
-            comments.append(comment.serializable(user_id))
-
+        data = {'source': node.source,
+                'comments': [comment.serializable(user_id)
+                             for comment in node.comments]}
         session.close()
-        return comments
-
-    def add_proposal(self, parent_id, text, displayed, username, 
-                    rating, time):
-        time = time or datetime.now()
-        
-        session = Session()
-        
-        node = session.query(Node).filter(Node.id == parent_id).first()
-        proposal= Proposal(text, displayed, username, rating, time, node)
-            
-        session.add(proposal)
-        session.commit()
-        session.close()
-        return proposal
-
-    def get_proposals(self, parent_id):
-        session = Session()
-        node = session.query(Node).filter(Node.id == parent_id).first()
-        proposals = []
-
-        # TODO
-
-        return proposals
+        return data
 
     def process_vote(self, comment_id, user_id, value):
         session = Session()

From c23e26833a187be135244828633c76180b0caada Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 27 Jul 2010 16:12:35 -0500
Subject: [PATCH 053/127] added ugly proposals

---
 sphinx/websupport/__init__.py                 | 74 ++++++++++++++++---
 sphinx/websupport/comments/__init__.py        | 10 ++-
 sphinx/websupport/comments/db.py              |  5 +-
 .../websupport/comments/sqlalchemystorage.py  | 32 ++++----
 4 files changed, 95 insertions(+), 26 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 452dc2950..3fd9d83b7 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -10,7 +10,10 @@
 """
 
 import cPickle as pickle
+import re
 from os import path
+from cgi import escape
+from difflib import Differ
 from datetime import datetime
 
 from jinja2 import Environment, FileSystemLoader
@@ -203,17 +206,16 @@ class WebSupport(object):
         :param rating: the starting rating of the comment, defaults to 0.
         :param time: the time the comment was created, defaults to now.
         """
-        return self.storage.add_comment(parent_id, text, displayed, 
-                                         username, rating, time, proposal)
+        id = parent_id[1:]
+        is_node = parent_id[0] == 's'
+
+        node = self.storage.get_node(id) if is_node else None
+        parent = self.storage.get_comment(id) if not is_node else None
+        diff = get_diff_html(node.source, proposal) if proposal else None
+
+        return self.storage.add_comment(text, displayed, username, rating, 
+                                        time, proposal, diff, node, parent)
     
-    def get_proposals(self, node_id, user_id=None):
-        return self.storage.get_proposals(node_id, user_id)
-
-    def add_proposal(self, parent_id, text, displayed=True, username=None,
-                    rating=0, time=None):
-        return self.storage.add_proposal(parent_id, text, displayed, 
-                                          username, rating, time)
-
     def process_vote(self, comment_id, user_id, value):
         """Process a user's vote. The web support package relies
         on the API user to perform authentication. The API user will 
@@ -240,3 +242,55 @@ class WebSupport(object):
         """
         value = int(value)
         self.storage.process_vote(comment_id, user_id, value)
+
+highlight_regex = re.compile(r'([\+\-\^]+)')
+
+def highlight_text(text, next, tag):
+    next = next[2:]
+    new_text = []
+    start = 0
+    for match in highlight_regex.finditer(next):
+        new_text.append(text[start:match.start()])
+        new_text.append('<%s>' % tag)
+        new_text.append(text[match.start():match.end()])
+        new_text.append('</%s>' % tag)
+        start = match.end()
+    new_text.append(text[start:])
+    return ''.join(new_text)
+
+def get_diff_html(source, proposal):
+    proposal = escape(proposal)
+
+    def handle_line(line, next=None):
+        prefix = line[0]
+        text = line[2:]
+
+        if prefix == ' ':
+            return text
+        elif prefix == '?':
+            return ''
+        
+        if next[0] == '?':
+            tag = 'ins' if prefix == '+' else 'del'
+            text = highlight_text(text, next, tag)
+        css_class = 'prop_added' if prefix == '+' else 'prop_removed'
+        
+        return '<span class="%s">%s</span>\n' % (css_class, text.rstrip())
+
+    differ = Differ()
+    diff = list(differ.compare(source.splitlines(1), proposal.splitlines(1)))
+
+    html = []
+    line = diff.pop(0)
+    next = diff.pop(0)
+    while True:
+        html.append(handle_line(line, next))
+        line = next
+        try:
+            next = diff.pop(0)
+        except IndexError:
+            handle_line(line)
+            break
+
+    return ''.join(html)
+
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 8cd3c36c4..0d9fa1549 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -19,6 +19,9 @@ class StorageBackend(object):
         """
         raise NotImplementedError()
     
+    def get_node(self, node_id):
+        raise NotImplementedError()
+
     def post_build(self):
         """Called after a build has completed. Use this to finalize the
         addition of nodes if needed.
@@ -26,11 +29,14 @@ class StorageBackend(object):
         pass
 
     def add_comment(self, parent_id, text, displayed, 
-                    username, rating, time, proposal):
+                    username, rating, time, proposal, proposal_diff):
         """Called when a comment is being added."""
         raise NotImplementedError()
 
-    def get_comments(self, parent_id):
+    def get_comment(self, comment_id):
+        raise NotImplementedError()
+
+    def get_comments(self, parent_id, user_id):
         """Called to retrieve all comments for a node."""
         raise NotImplementedError()
 
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index 3679e3d6d..e55b6af27 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -38,6 +38,7 @@ class Comment(Base):
     displayed = Column(Boolean, index=True, default=False)
     username = Column(String(64))
     proposal = Column(Text)
+    proposal_diff = Column(Text)
 
     node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
     node = relation(Node, backref='comments')
@@ -46,7 +47,7 @@ class Comment(Base):
     parent = relation('Comment', backref='children', remote_side=[id])
 
     def __init__(self, text, displayed, username, rating, time, 
-                 proposal, node=None, parent=None):
+                 proposal, proposal_diff, node, parent):
         self.text = text
         self.displayed = displayed
         self.username = username
@@ -55,6 +56,7 @@ class Comment(Base):
         self.node = node
         self.parent = parent
         self.proposal = proposal
+        self.proposal_diff = proposal_diff
 
     def serializable(self, user_id=None):
         delta = datetime.now() - self.time
@@ -86,6 +88,7 @@ class Comment(Base):
                 'vote': vote or 0,
                 'node': self.node.id if self.node else None,
                 'parent': self.parent.id if self.parent else None,
+                'proposal_diff': self.proposal_diff,
                 'children': [child.serializable(user_id) 
                              for child in self.children]}
 
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 706ea4c03..067815a9c 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -19,32 +19,39 @@ class SQLAlchemyStorage(StorageBackend):
         self.build_session.flush()
         return node.id
 
+    def get_node(self, node_id):
+        session = Session()
+        node = session.query(Node).filter(Node.id == node_id).first()
+        session.close()
+        return node
+
     def post_build(self):
         self.build_session.commit()
         self.build_session.close()
 
-    def add_comment(self, parent_id, text, displayed, 
-                    username, rating, time, proposal):
+    def add_comment(self, text, displayed, username, rating, time, 
+                    proposal, proposal_diff, node=None, parent=None):
         time = time or datetime.now()
         
         session = Session()
         
-        id = parent_id[1:]
-        if parent_id[0] == 's':
-            node = session.query(Node).filter(Node.id == id).first()
-            comment = Comment(text, displayed, username, rating, 
-                              time, proposal, node=node)
-        elif parent_id[0] == 'c':
-            parent = session.query(Comment).filter(Comment.id == id).first()
-            comment = Comment(text, displayed, username, rating, 
-                              time,proposal, parent=parent)
-            
+        comment = Comment(text, displayed, username, rating, time,
+                          proposal, proposal_diff, node, parent)
+
         session.add(comment)
         session.commit()
         comment = comment.serializable()
         session.close()
         return comment
         
+    def get_comment(self, comment_id):
+        session = Session()
+        comment = session.query(Comment) \
+            .filter(Comment.id == comment_id).first()
+        session.close()
+        return comment 
+
+
     def get_comments(self, parent_id, user_id):
         parent_id = parent_id[1:]
         session = Session()
@@ -73,4 +80,3 @@ class SQLAlchemyStorage(StorageBackend):
         session.add(vote)
         session.commit()
         session.close()
-

From 0039b09a36b0d7e4e787185eff4499b33b237990 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 27 Jul 2010 21:16:07 -0500
Subject: [PATCH 054/127] fix regression that caused error when replying to a
 comment

---
 sphinx/websupport/__init__.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index d64c4ff18..9d5f0cbac 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -210,7 +210,10 @@ class WebSupport(object):
         is_node = parent_id[0] == 's'
         node = self.storage.get_node(id) if is_node else None
         parent = self.storage.get_comment(id) if not is_node else None
-        diff = get_diff_html(node.source, proposal) if proposal else None
+        if node and proposal:
+            diff = get_diff_html(node.source, proposal)
+        else:
+            diff = None
         return self.storage.add_comment(text, displayed, username, rating,
                                         time, proposal, diff, node, parent)
 

From f014641405385f8477f221242274c188aab0e172 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 30 Jul 2010 11:20:43 -0500
Subject: [PATCH 055/127] Added test for build and made web support buildable
 without specifying search adapter

---
 sphinx/websupport/__init__.py          | 21 ++++++------
 sphinx/websupport/search/__init__.py   |  5 +++
 sphinx/websupport/search/nullsearch.py | 22 ++++++++++++
 tests/test_websupport.py               | 47 ++++++++++++++++++++++++++
 4 files changed, 85 insertions(+), 10 deletions(-)
 create mode 100644 sphinx/websupport/search/nullsearch.py
 create mode 100644 tests/test_websupport.py

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 9d5f0cbac..4d73c0e10 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -10,7 +10,7 @@
 """
 
 import cPickle as pickle
-import re
+import re, sys
 from os import path
 from cgi import escape
 from difflib import Differ
@@ -35,7 +35,7 @@ class WebSupport(object):
     """
 
     def __init__(self, srcdir='', outdir='', datadir='', search=None,
-                 storage=None):
+                 storage=None, status=sys.stdout, warning=sys.stderr):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
@@ -43,9 +43,10 @@ class WebSupport(object):
 
         self.outdir = outdir or datadir
 
-        if search is not None:
-            self._init_search(search)
+        self.status = status
+        self.warning = warning
 
+        self._init_search(search)            
         self._init_storage(storage)
 
     def _init_storage(self, storage):
@@ -73,11 +74,11 @@ class WebSupport(object):
         if isinstance(search, BaseSearch):
             self.search = search
         else:
-            mod, cls = search_adapters[search]
-            search_class = getattr(__import__('sphinx.websupport.search.' + mod,
-                                          None, None, [cls]), cls)
+            mod, cls = search_adapters[search or 'null']
+            mod = 'sphinx.websupport.search.' + mod
+            SearchClass = getattr(__import__(mod, None, None, [cls]), cls)
             search_path = path.join(self.outdir, 'search')
-            self.search = search_class(search_path)
+            self.search = SearchClass(search_path)
         self.results_template = \
             self.template_env.get_template('searchresults.html')
 
@@ -95,8 +96,8 @@ class WebSupport(object):
         doctreedir = path.join(self.outdir, 'doctrees')
         app = WebSupportApp(self.srcdir, self.srcdir,
                             self.outdir, doctreedir, 'websupport',
-                            search=self.search,
-                            storage=self.storage)
+                            search=self.search, status=self.status, 
+                            warning=self.warning, storage=self.storage)
 
         self.storage.pre_build()
         app.build()
diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index e1d7ea471..d41b560c3 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -12,6 +12,9 @@
 import re
 
 class BaseSearch(object):
+    def __init__(self, path):
+        pass
+
     def init_indexing(self, changed=[]):
         """Called by the builder to initialize the search indexer. `changed`
         is a list of pagenames that will be reindexed. You may want to remove
@@ -117,4 +120,6 @@ class BaseSearch(object):
 search_adapters = {
     'xapian': ('xapiansearch', 'XapianSearch'),
     'whoosh': ('whooshsearch', 'WhooshSearch'),
+    'null': ('nullsearch', 'NullSearch')
     }
+
diff --git a/sphinx/websupport/search/nullsearch.py b/sphinx/websupport/search/nullsearch.py
new file mode 100644
index 000000000..ad3d7daef
--- /dev/null
+++ b/sphinx/websupport/search/nullsearch.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.search.nullsearch
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    The default search adapter, does nothing.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from sphinx.websupport.search import BaseSearch
+
+class NullSearchException(Exception):
+    pass
+
+class NullSearch(BaseSearch):
+    def feed(self, pagename, title, doctree):
+        pass
+
+    def query(self, q):
+        raise NullSearchException('No search adapter specified.')
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
new file mode 100644
index 000000000..d9251eb61
--- /dev/null
+++ b/tests/test_websupport.py
@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+"""
+    test_websupport
+    ~~~~~~~~~~~~~~~
+
+    Test the Web Support Package
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import os
+from StringIO import StringIO
+
+from sphinx.websupport import WebSupport
+
+try:
+    from functools import wraps
+except ImportError:
+    # functools is new in 2.4
+    wraps = lambda f: (lambda w: w)
+
+from util import *
+
+def teardown_module():
+    (test_root / 'websupport').rmtree(True)
+
+def with_support(*args, **kwargs):
+    """Make a WebSupport object and pass it the test."""
+    settings = {'srcdir': test_root,
+                'outdir': os.path.join(test_root, 'websupport'),
+                'status': StringIO(),
+                'warning': StringIO()}
+    settings.update(kwargs)
+
+    def generator(func):
+        @wraps(func)
+        def new_func(*args2, **kwargs2):
+            support = WebSupport(**settings)
+            func(support, *args2, **kwargs2)
+        return new_func
+    return generator
+
+@with_support()
+def test_build(support):
+    support.build()
+    

From 846ab3a74374a1f7e72d5e7a56857beb8eb494f4 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 30 Jul 2010 15:53:02 -0500
Subject: [PATCH 056/127] Added DocumentNotFoundError

---
 sphinx/websupport/__init__.py | 9 ++++++++-
 tests/test_websupport.py      | 2 ++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 4d73c0e10..6c2920708 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -22,6 +22,7 @@ from sphinx.application import Sphinx
 from sphinx.util.osutil import ensuredir
 from sphinx.websupport.search import BaseSearch, search_adapters
 from sphinx.websupport.comments import StorageBackend
+from sphinx.websupport.errors import DocumentNotFoundError
 
 class WebSupportApp(Sphinx):
     def __init__(self, *args, **kwargs):
@@ -126,7 +127,13 @@ class WebSupport(object):
         :param docname: the name of the document to load.
         """
         infilename = path.join(self.outdir, docname + '.fpickle')
-        f = open(infilename, 'rb')
+
+        try:
+            f = open(infilename, 'rb')
+        except IOError:
+            raise DocumentNotFoundError(
+                'The document "%s" could not be found' % docname)
+
         document = pickle.load(f)
         return document
 
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index d9251eb61..80a4affed 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -13,6 +13,7 @@ import os
 from StringIO import StringIO
 
 from sphinx.websupport import WebSupport
+from sphinx.websupport.errors import DocumentNotFoundError
 
 try:
     from functools import wraps
@@ -44,4 +45,5 @@ def with_support(*args, **kwargs):
 @with_support()
 def test_build(support):
     support.build()
+    raises(DocumentNotFoundError, support.get_document, 'nonexisting')
     

From 2528f3ddce3209fec1b4910cfbb73d291ac5a25b Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 30 Jul 2010 16:13:51 -0500
Subject: [PATCH 057/127] Added SrcdirNotSpecifiedError

---
 sphinx/websupport/__init__.py |  5 ++++-
 tests/test_websupport.py      | 19 ++++++++++++++++---
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 6c2920708..ae55ee2e8 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -22,7 +22,7 @@ from sphinx.application import Sphinx
 from sphinx.util.osutil import ensuredir
 from sphinx.websupport.search import BaseSearch, search_adapters
 from sphinx.websupport.comments import StorageBackend
-from sphinx.websupport.errors import DocumentNotFoundError
+from sphinx.websupport.errors import *
 
 class WebSupportApp(Sphinx):
     def __init__(self, *args, **kwargs):
@@ -94,6 +94,9 @@ class WebSupport(object):
         build the pickles and search index, placing them into `outdir`.
         It will also save node data to the database.
         """
+        if not self.srcdir:
+            raise SrcdirNotSpecifiedError( \
+                'No srcdir associated with WebSupport object')
         doctreedir = path.join(self.outdir, 'doctrees')
         app = WebSupportApp(self.srcdir, self.srcdir,
                             self.outdir, doctreedir, 'websupport',
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 80a4affed..b8884bf91 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -13,7 +13,7 @@ import os
 from StringIO import StringIO
 
 from sphinx.websupport import WebSupport
-from sphinx.websupport.errors import DocumentNotFoundError
+from sphinx.websupport.errors import *
 
 try:
     from functools import wraps
@@ -23,13 +23,14 @@ except ImportError:
 
 from util import *
 
+
 def teardown_module():
     (test_root / 'websupport').rmtree(True)
 
+
 def with_support(*args, **kwargs):
     """Make a WebSupport object and pass it the test."""
-    settings = {'srcdir': test_root,
-                'outdir': os.path.join(test_root, 'websupport'),
+    settings = {'outdir': os.path.join(test_root, 'websupport'),
                 'status': StringIO(),
                 'warning': StringIO()}
     settings.update(kwargs)
@@ -42,8 +43,20 @@ def with_support(*args, **kwargs):
         return new_func
     return generator
 
+
 @with_support()
+def test_no_srcdir(support):
+    """Make sure the correct exception is raised if srcdir is not given."""
+    raises(SrcdirNotSpecifiedError, support.build)
+
+@with_support(srcdir=test_root)
 def test_build(support):
     support.build()
+
+@with_support()
+def test_get_document(support):
     raises(DocumentNotFoundError, support.get_document, 'nonexisting')
     
+    contents = support.get_document('contents')
+    assert contents['title'] and contents['body'] \
+        and contents['sidebar'] and contents['relbar']

From bc155cac92da11d738af89b128ad7f3ff137bd76 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 30 Jul 2010 16:15:41 -0500
Subject: [PATCH 058/127] Somehow I always forget to add files...
 (sphinx.websupport.errors)

---
 sphinx/websupport/errors.py | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 sphinx/websupport/errors.py

diff --git a/sphinx/websupport/errors.py b/sphinx/websupport/errors.py
new file mode 100644
index 000000000..b1c47915e
--- /dev/null
+++ b/sphinx/websupport/errors.py
@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.errors
+    ~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Contains Error classes for the web support package.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+__all__ = ['DocumentNotFoundError', 'SrcdirNotSpecifiedError']
+
+class DocumentNotFoundError(Exception):
+    pass
+
+
+class SrcdirNotSpecifiedError(Exception):
+    pass

From a36175298e252c4a92902e5c35a5f52ec35edaab Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 30 Jul 2010 17:07:48 -0500
Subject: [PATCH 059/127] Added basic search tests.

---
 tests/test_websupport.py | 50 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 45 insertions(+), 5 deletions(-)

diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index b8884bf91..3d61e55c2 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -9,7 +9,7 @@
     :license: BSD, see LICENSE for details.
 """
 
-import os
+import os, sys
 from StringIO import StringIO
 
 from sphinx.websupport import WebSupport
@@ -24,15 +24,22 @@ except ImportError:
 from util import *
 
 
-def teardown_module():
+default_settings = {'outdir': os.path.join(test_root, 'websupport'),
+                    'status': StringIO(),
+                    'warning': StringIO()}
+
+
+def clear_builddir():
     (test_root / 'websupport').rmtree(True)
 
 
+def teardown_module():
+    clear_builddir()
+
+
 def with_support(*args, **kwargs):
     """Make a WebSupport object and pass it the test."""
-    settings = {'outdir': os.path.join(test_root, 'websupport'),
-                'status': StringIO(),
-                'warning': StringIO()}
+    settings = default_settings.copy()
     settings.update(kwargs)
 
     def generator(func):
@@ -49,10 +56,12 @@ def test_no_srcdir(support):
     """Make sure the correct exception is raised if srcdir is not given."""
     raises(SrcdirNotSpecifiedError, support.build)
 
+
 @with_support(srcdir=test_root)
 def test_build(support):
     support.build()
 
+
 @with_support()
 def test_get_document(support):
     raises(DocumentNotFoundError, support.get_document, 'nonexisting')
@@ -60,3 +69,34 @@ def test_get_document(support):
     contents = support.get_document('contents')
     assert contents['title'] and contents['body'] \
         and contents['sidebar'] and contents['relbar']
+
+
+def search_adapter_helper(adapter):
+    clear_builddir()
+    
+    settings = default_settings.copy()
+    settings.update({'srcdir': test_root,
+                     'search': adapter})
+    support = WebSupport(**settings)
+    
+    support.build()
+
+
+def test_xapian():
+    # Don't run tests if xapian is not installed.
+    try:
+        import xapian
+        search_adapter_helper('xapian')
+    except ImportError:
+        sys.stderr.write('info: not running xapian tests, ' \
+                         'xapian doesn\'t seem to be installed')
+
+
+def test_whoosh():
+    # Don't run tests if xapian is not installed.
+    try:
+        import whoosh
+        search_adapter_helper('whoosh')
+    except ImportError:
+        sys.stderr.write('info: not running xapian tests, ' \
+                         'whoosh doesn\'t seem to be installed')

From a31f3b7e73f2050efab07a9ed143c72e774af452 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 31 Jul 2010 12:23:26 -0500
Subject: [PATCH 060/127] More complete tests for search adapters.

---
 sphinx/websupport/search/__init__.py     |  2 +-
 sphinx/websupport/search/whooshsearch.py |  2 ++
 tests/test_websupport.py                 | 25 +++++++++++++++++++++++-
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index d41b560c3..0e613222e 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -83,7 +83,7 @@ class BaseSearch(object):
         query `q`. This should return an iterable containing tuples of the
         following format::
 
-            (<path>, <title> <context>)
+            (<path>, <title>, <context>)
 
         `path` and `title` are the same values that were passed to
         :meth:`add_document`, and `context` should be a short text snippet
diff --git a/sphinx/websupport/search/whooshsearch.py b/sphinx/websupport/search/whooshsearch.py
index 658b764dd..257393a6a 100644
--- a/sphinx/websupport/search/whooshsearch.py
+++ b/sphinx/websupport/search/whooshsearch.py
@@ -40,6 +40,8 @@ class WhooshSearch(BaseSearch):
 
     def finish_indexing(self):
         self.index_writer.commit()
+        # Create a new searcher so changes can be seen immediately
+        self.searcher = self.index.searcher()
 
     def add_document(self, pagename, title, text):
         self.index_writer.add_document(path=unicode(pagename),
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 3d61e55c2..3f352cd6c 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -78,9 +78,32 @@ def search_adapter_helper(adapter):
     settings.update({'srcdir': test_root,
                      'search': adapter})
     support = WebSupport(**settings)
-    
     support.build()
 
+    s = support.search
+
+    # Test the adapters query method. A search for "Epigraph" should return
+    # one result.
+    results = s.query(u'Epigraph')
+    assert len(results) == 1, \
+        '%s search adapter returned %s search result(s), should have been 1'\
+        % (adapter, len(results))
+
+    # Make sure documents are properly updated by the search adapter.
+    s.init_indexing(changed=['markup'])
+    s.add_document(u'markup', u'title', u'SomeLongRandomWord')
+    s.finish_indexing()
+    # Now a search for "Epigraph" should return zero results.
+    results = s.query(u'Epigraph')
+    assert len(results) == 0, \
+        '%s search adapter returned %s search result(s), should have been 0'\
+        % (adapter, len(results))
+    # A search for "SomeLongRandomWord" should return one result.
+    results = s.query(u'SomeLongRandomWord')
+    assert len(results) == 1, \
+        '%s search adapter returned %s search result(s), should have been 1'\
+        % (adapter, len(results))
+    
 
 def test_xapian():
     # Don't run tests if xapian is not installed.

From 682fa466fe70704c7e58c703a387dcb082f56518 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 31 Jul 2010 15:51:13 -0500
Subject: [PATCH 061/127] Added test for comment system.

---
 tests/test_websupport.py | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 3f352cd6c..53307fb4e 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -14,6 +14,8 @@ from StringIO import StringIO
 
 from sphinx.websupport import WebSupport
 from sphinx.websupport.errors import *
+from sphinx.websupport.comments.sqlalchemystorage import Session
+from sphinx.websupport.comments.db import Node
 
 try:
     from functools import wraps
@@ -116,10 +118,25 @@ def test_xapian():
 
 
 def test_whoosh():
-    # Don't run tests if xapian is not installed.
+    # Don't run tests if whoosh is not installed.
     try:
         import whoosh
         search_adapter_helper('whoosh')
     except ImportError:
-        sys.stderr.write('info: not running xapian tests, ' \
+        sys.stderr.write('info: not running whoosh tests, ' \
                          'whoosh doesn\'t seem to be installed')
+
+
+@with_support()
+def test_comments(support):
+    session = Session()
+    node = session.query(Node).first()
+    comment = support.add_comment('First test comment', node=str(node.id))
+    support.add_comment('Child test comment', parent=str(comment['id']))
+    data = support.get_comments(str(node.id))
+    comments = data['comments']
+    children = comments[0]['children']
+    assert len(comments) == 1
+    assert comments[0]['text'] == 'First test comment'
+    assert len(children) == 1
+    assert children[0]['text'] == 'Child test comment'

From 92e0cfc00100dc80719ac1819f5362e2468e549b Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 31 Jul 2010 15:53:13 -0500
Subject: [PATCH 062/127] refactored add_comment and get_comments; added
 CombinedHtmlDiff class

---
 sphinx/websupport/__init__.py                 | 91 ++++---------------
 sphinx/websupport/comments/__init__.py        | 10 +-
 sphinx/websupport/comments/differ.py          | 66 ++++++++++++++
 .../websupport/comments/sqlalchemystorage.py  | 41 ++++-----
 4 files changed, 105 insertions(+), 103 deletions(-)
 create mode 100644 sphinx/websupport/comments/differ.py

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index ae55ee2e8..7af8aa1cb 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -9,11 +9,9 @@
     :license: BSD, see LICENSE for details.
 """
 
+import sys
 import cPickle as pickle
-import re, sys
 from os import path
-from cgi import escape
-from difflib import Differ
 from datetime import datetime
 
 from jinja2 import Environment, FileSystemLoader
@@ -195,20 +193,25 @@ class WebSupport(object):
         """
         return self.storage.get_comments(node_id, user_id)
 
-    def add_comment(self, parent_id, text, displayed=True, username=None,
-                    rating=0, time=None, proposal=None):
-        """Add a comment to a node or another comment. `parent_id` will have
-        a one letter prefix, distinguishing between node parents and 
-        comment parents, 'c' and 's' respectively. This function will
-        return the comment in the same format as :meth:`get_comments`.
-        Usage is simple::
+    def add_comment(self, text, node='', parent='', displayed=True, 
+                    username=None, rating=0, time=None, proposal=None):
+        """Add a comment to a node or another comment. Returns the comment 
+        in the same format as :meth:`get_comments`. If the comment is being 
+        attached to a node, pass in the node's id (as a string) with the 
+        node keyword argument::
+
+            comment = support.add_comment(text, node=node_id)
+
+        If the comment is the child of another comment, provide the parent's
+        id (as a string) with the parent keyword argument::
+            
+            comment = support.add_comment(text, parent=parent_id)
 
-            comment = support.add_comment(parent_id, text)
-        
         If you would like to store a username with the comment, pass
         in the optional `username` keyword argument::
 
-            comment = support.add_comment(parent_id, text, username=username)
+            comment = support.add_comment(text, node=node_id, 
+                                          username=username)
 
         :param parent_id: the prefixed id of the comment's parent.
         :param text: the text of the comment.
@@ -217,16 +220,8 @@ class WebSupport(object):
         :param rating: the starting rating of the comment, defaults to 0.
         :param time: the time the comment was created, defaults to now.
         """
-        id = parent_id[1:]
-        is_node = parent_id[0] == 's'
-        node = self.storage.get_node(id) if is_node else None
-        parent = self.storage.get_comment(id) if not is_node else None
-        if node and proposal:
-            diff = get_diff_html(node.source, proposal)
-        else:
-            diff = None
         return self.storage.add_comment(text, displayed, username, rating,
-                                        time, proposal, diff, node, parent)
+                                        time, proposal, node, parent)
 
     def process_vote(self, comment_id, user_id, value):
         """Process a user's vote. The web support package relies
@@ -254,55 +249,3 @@ class WebSupport(object):
         """
         value = int(value)
         self.storage.process_vote(comment_id, user_id, value)
-
-highlight_regex = re.compile(r'([\+\-\^]+)')
-
-def highlight_text(text, next, tag):
-    next = next[2:]
-    new_text = []
-    start = 0
-    for match in highlight_regex.finditer(next):
-        new_text.append(text[start:match.start()])
-        new_text.append('<%s>' % tag)
-        new_text.append(text[match.start():match.end()])
-        new_text.append('</%s>' % tag)
-        start = match.end()
-    new_text.append(text[start:])
-    return ''.join(new_text)
-
-def get_diff_html(source, proposal):
-    proposal = escape(proposal)
-
-    def handle_line(line, next=None):
-        prefix = line[0]
-        text = line[2:]
-
-        if prefix == ' ':
-            return text
-        elif prefix == '?':
-            return ''
-        
-        if next[0] == '?':
-            tag = 'ins' if prefix == '+' else 'del'
-            text = highlight_text(text, next, tag)
-        css_class = 'prop_added' if prefix == '+' else 'prop_removed'
-        
-        return '<span class="%s">%s</span>\n' % (css_class, text.rstrip())
-
-    differ = Differ()
-    diff = list(differ.compare(source.splitlines(1), proposal.splitlines(1)))
-
-    html = []
-    line = diff.pop(0)
-    next = diff.pop(0)
-    while True:
-        html.append(handle_line(line, next))
-        line = next
-        try:
-            next = diff.pop(0)
-        except IndexError:
-            handle_line(line)
-            break
-
-    return ''.join(html)
-
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 2daf9b64b..3d7f51542 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -29,23 +29,17 @@ class StorageBackend(object):
         """
         raise NotImplementedError()
     
-    def get_node(self, node_id):
-        raise NotImplementedError()
-
     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, proposal, proposal_diff):
+    def add_comment(self, text, displayed, username, rating, time,
+                    proposal, node, parent):
         """Called when a comment is being added."""
         raise NotImplementedError()
 
-    def get_comment(self, comment_id):
-        raise NotImplementedError()
-
     def get_comments(self, parent_id, user_id):
         """Called to retrieve all comments for a node."""
         raise NotImplementedError()
diff --git a/sphinx/websupport/comments/differ.py b/sphinx/websupport/comments/differ.py
new file mode 100644
index 000000000..786922346
--- /dev/null
+++ b/sphinx/websupport/comments/differ.py
@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.websupport.comments.differ
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    A differ for creating an HTML representations of proposal diffs
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import re
+from cgi import escape
+from difflib import Differ
+
+class CombinedHtmlDiff(object):
+
+    highlight_regex = re.compile(r'([\+\-\^]+)')
+
+    def _highlight_text(self, text, next, tag):
+        next = next[2:]
+        new_text = []
+        start = 0
+        for match in highlight_regex.finditer(next):
+            new_text.append(text[start:match.start()])
+            new_text.append('<%s>' % tag)
+            new_text.append(text[match.start():match.end()])
+            new_text.append('</%s>' % tag)
+            start = match.end()
+        new_text.append(text[start:])
+        return ''.join(new_text)
+
+    def _handle_line(line, next=None):
+        prefix = line[0]
+        text = line[2:]
+
+        if prefix == ' ':
+            return text
+        elif prefix == '?':
+            return ''
+        
+        if next[0] == '?':
+            tag = 'ins' if prefix == '+' else 'del'
+            text = self._highlight_text(text, next, tag)
+        css_class = 'prop_added' if prefix == '+' else 'prop_removed'
+        
+        return '<span class="%s">%s</span>\n' % (css_class, text.rstrip())
+
+    def make_html(self, source, proposal):
+        proposal = escape(proposal)
+
+        differ = Differ()
+        diff = list(differ.compare(source.splitlines(1),
+                                   proposal.splitlines(1)))
+        html = []
+        line = diff.pop(0)
+        next = diff.pop(0)
+        while True:
+            html.append(self._handle_line(line, next))
+            line = next
+            try:
+                next = diff.pop(0)
+            except IndexError:
+                self._handle_line(line)
+                break
+        return ''.join(html)
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 6c9b06b3b..294c48f44 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -14,6 +14,7 @@ from datetime import datetime
 from sphinx.websupport.comments import StorageBackend
 from sphinx.websupport.comments.db import Base, Node, Comment, CommentVote,\
                                           Session
+from sphinx.websupport.comments.differ import CombinedHtmlDiff
 
 class SQLAlchemyStorage(StorageBackend):
     def __init__(self, engine):
@@ -31,41 +32,39 @@ class SQLAlchemyStorage(StorageBackend):
         self.build_session.flush()
         return node.id
 
-    def get_node(self, node_id):
-        session = Session()
-        node = session.query(Node).filter(Node.id == node_id).first()
-        session.close()
-        return node
-
     def post_build(self):
         self.build_session.commit()
         self.build_session.close()
 
     def add_comment(self, text, displayed, username, rating, time,
-                    proposal, proposal_diff, node=None, parent=None):
-        time = time or datetime.now()
-
+                    proposal, node, parent):
         session = Session()
         
-        comment = Comment(text, displayed, username, rating, time,
-                          proposal, proposal_diff, node, parent)
+        if node:
+            node = session.query(Node).filter(Node.id == node).first()
+            parent = None
+        else:
+            node = None
+            parent = session.query(Comment).filter(
+                Comment.id == parent).first()
+        if node and proposal:
+            differ = CombinedHtmlDiff()
+            proposal_diff = differ.make_html(node.source, proposal)
+        else:
+            proposal_diff = None
+
+        comment = Comment(text, displayed, username, rating, 
+                          time or datetime.now(), proposal, proposal_diff, 
+                          node, parent)
         session.add(comment)
         session.commit()
         comment = comment.serializable()
         session.close()
         return comment
 
-    def get_comment(self, comment_id):
+    def get_comments(self, node_id, user_id):
         session = Session()
-        comment = session.query(Comment) \
-            .filter(Comment.id == comment_id).first()
-        session.close()
-        return comment
-
-    def get_comments(self, parent_id, user_id):
-        parent_id = parent_id[1:]
-        session = Session()
-        node = session.query(Node).filter(Node.id == parent_id).first()
+        node = session.query(Node).filter(Node.id == node_id).first()
         data = {'source': node.source,
                 'comments': [comment.serializable(user_id)
                              for comment in node.comments]}

From 62fe57c64118f45051f6d72c87a4032db436c88d Mon Sep 17 00:00:00 2001
From: jacob <jacob@panther>
Date: Tue, 3 Aug 2010 12:21:43 -0500
Subject: [PATCH 063/127] Converted comment schema from adjacency list to
 materialized path. Added tests for commments. Layed groundwork for comment
 moderation.

---
 sphinx/websupport/__init__.py                 | 20 +++--
 sphinx/websupport/comments/__init__.py        |  2 +-
 sphinx/websupport/comments/db.py              | 52 ++++++------
 .../websupport/comments/sqlalchemystorage.py  | 79 ++++++++++++++-----
 tests/test_websupport.py                      | 57 ++++++++++++-
 5 files changed, 147 insertions(+), 63 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 7af8aa1cb..373622eb1 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -157,7 +157,7 @@ class WebSupport(object):
         document['title'] = 'Search Results'
         return document
 
-    def get_comments(self, node_id, user_id=None):
+    def get_comments(self, node_id, username=None, moderator=False):
         """Get the comments and source associated with `node_id`. If 
         `user_id` is given vote information will be included with the 
         returned comments. The default CommentBackend returns dict with
@@ -191,10 +191,11 @@ class WebSupport(object):
         :param node_id: the id of the node to get comments for.
         :param user_id: the id of the user viewing the comments.
         """
-        return self.storage.get_comments(node_id, user_id)
+        return self.storage.get_comments(node_id, username, moderator)
 
-    def add_comment(self, text, node='', parent='', displayed=True, 
-                    username=None, rating=0, time=None, proposal=None):
+    def add_comment(self, text, node_id='', parent_id='', displayed=True, 
+                    username=None, rating=0, time=None, proposal=None,
+                    moderator=False):
         """Add a comment to a node or another comment. Returns the comment 
         in the same format as :meth:`get_comments`. If the comment is being 
         attached to a node, pass in the node's id (as a string) with the 
@@ -215,15 +216,16 @@ class WebSupport(object):
 
         :param parent_id: the prefixed id of the comment's parent.
         :param text: the text of the comment.
-        :param displayed: for future use...
+        :param displayed: for moderation purposes
         :param username: the username of the user making the comment.
         :param rating: the starting rating of the comment, defaults to 0.
         :param time: the time the comment was created, defaults to now.
         """
         return self.storage.add_comment(text, displayed, username, rating,
-                                        time, proposal, node, parent)
+                                        time, proposal, node_id, parent_id, 
+                                        moderator)
 
-    def process_vote(self, comment_id, user_id, value):
+    def process_vote(self, comment_id, username, value):
         """Process a user's vote. The web support package relies
         on the API user to perform authentication. The API user will 
         typically receive a comment_id and value from a form, and then
@@ -248,4 +250,6 @@ class WebSupport(object):
         :param value: 1 for an upvote, -1 for a downvote, 0 for an unvote.
         """
         value = int(value)
-        self.storage.process_vote(comment_id, user_id, value)
+        if not -1 <= value <= 1:
+            raise ValueError('vote value %s out of range (-1, 1)' % value)
+        self.storage.process_vote(comment_id, username, value)
diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/comments/__init__.py
index 3d7f51542..10856dffd 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/comments/__init__.py
@@ -40,7 +40,7 @@ class StorageBackend(object):
         """Called when a comment is being added."""
         raise NotImplementedError()
 
-    def get_comments(self, parent_id, user_id):
+    def get_comments(self, parent_id, user_id, moderator):
         """Called to retrieve all comments for a node."""
         raise NotImplementedError()
 
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/comments/db.py
index ecb62afa5..91175ed38 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/comments/db.py
@@ -32,7 +32,6 @@ class Node(Base):
     document = Column(String(256), nullable=False)
     line = Column(Integer)
     source = Column(Text, nullable=False)
-    treeloc = Column(String(32), nullable=False)
 
     def __init__(self, document, line, source, treeloc):
         self.document = document
@@ -51,26 +50,32 @@ class Comment(Base):
     username = Column(String(64))
     proposal = Column(Text)
     proposal_diff = Column(Text)
+    path = Column(String(256), index=True)
 
-    node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
-    node = relation(Node, backref='comments')
-
-    parent_id = Column(Integer, ForeignKey(db_prefix + 'comments.id'))
-    parent = relation('Comment', backref='children', remote_side=[id])
+    #node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
+    #node = relation(Node, backref='comments')
 
     def __init__(self, text, displayed, username, rating, time, 
-                 proposal, proposal_diff, node, parent):
+                 proposal, proposal_diff):
         self.text = text
         self.displayed = displayed
         self.username = username
         self.rating = rating
         self.time = time
-        self.node = node
-        self.parent = parent
         self.proposal = proposal
         self.proposal_diff = proposal_diff
 
-    def serializable(self, user_id=None):
+    def set_path(self, node_id, parent_id):
+        if node_id:
+            self.path = '%s.%s' % (node_id, self.id)
+        else:
+            session = Session()
+            parent_path = session.query(Comment.path).\
+                filter(Comment.id == parent_id).one().path
+            session.close()
+            self.path = '%s.%s' %  (parent_path, self.id)
+
+    def serializable(self, vote=0):
         delta = datetime.now() - self.time
 
         time = {'year': self.time.year,
@@ -82,15 +87,6 @@ class Comment(Base):
                 'iso': self.time.isoformat(),
                 'delta': self.pretty_delta(delta)}
 
-        vote = ''
-        if user_id is not None:
-            session = Session()
-            vote = session.query(CommentVote).filter(
-                CommentVote.comment_id == self.id).filter(
-                CommentVote.user_id == user_id).first()
-            vote = vote.value if vote is not None else 0
-            session.close()
-
         return {'text': self.text,
                 'username': self.username or 'Anonymous',
                 'id': self.id,
@@ -98,11 +94,8 @@ class Comment(Base):
                 'age': delta.seconds,
                 'time': time,
                 'vote': vote or 0,
-                'node': self.node.id if self.node else None,
-                'parent': self.parent.id if self.parent else None,
                 'proposal_diff': self.proposal_diff,
-                'children': [child.serializable(user_id)
-                             for child in self.children]}
+                'children': []}
 
     def pretty_delta(self, delta):
         days = delta.days
@@ -120,15 +113,14 @@ class Comment(Base):
 class CommentVote(Base):
     __tablename__ = db_prefix + 'commentvote'
 
-    user_id = Column(Integer, primary_key=True)
-    # -1 if downvoted, +1 if upvoted, 0 if voted then unvoted.
-    value = Column(Integer, nullable=False)
-
+    username = Column(String(64), primary_key=True)
     comment_id = Column(Integer, ForeignKey(db_prefix + 'comments.id'),
                         primary_key=True)
     comment = relation(Comment, backref="votes")
+    # -1 if downvoted, +1 if upvoted, 0 if voted then unvoted.
+    value = Column(Integer, nullable=False)
 
-    def __init__(self, comment_id, user_id, value):
-        self.value = value
-        self.user_id = user_id
+    def __init__(self, comment_id, username, value):
         self.comment_id = comment_id
+        self.username = username
+        self.value = value
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 294c48f44..0e11c4a09 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -11,6 +11,7 @@
 
 from datetime import datetime
 
+from sqlalchemy.orm import aliased
 from sphinx.websupport.comments import StorageBackend
 from sphinx.websupport.comments.db import Base, Node, Comment, CommentVote,\
                                           Session
@@ -37,51 +38,89 @@ class SQLAlchemyStorage(StorageBackend):
         self.build_session.close()
 
     def add_comment(self, text, displayed, username, rating, time,
-                    proposal, node, parent):
+                    proposal, node_id, parent_id, moderator):
         session = Session()
         
-        if node:
-            node = session.query(Node).filter(Node.id == node).first()
-            parent = None
-        else:
-            node = None
-            parent = session.query(Comment).filter(
-                Comment.id == parent).first()
-        if node and proposal:
+        if node_id and proposal:
             differ = CombinedHtmlDiff()
             proposal_diff = differ.make_html(node.source, proposal)
         else:
             proposal_diff = None
 
         comment = Comment(text, displayed, username, rating, 
-                          time or datetime.now(), proposal, proposal_diff, 
-                          node, parent)
+                          time or datetime.now(), proposal, proposal_diff)
         session.add(comment)
+        session.flush()
+        comment.set_path(node_id, parent_id)
         session.commit()
         comment = comment.serializable()
         session.close()
         return comment
 
-    def get_comments(self, node_id, user_id):
+    def get_comments(self, node_id, username, moderator):
         session = Session()
-        node = session.query(Node).filter(Node.id == node_id).first()
-        data = {'source': node.source,
-                'comments': [comment.serializable(user_id)
-                             for comment in node.comments]}
+        node = session.query(Node).filter(Node.id == node_id).one()
         session.close()
-        return data
+        comments = self._serializable_list(node_id, username, moderator)
+        return {'source': node.source,
+                'comments': comments}
 
-    def process_vote(self, comment_id, user_id, value):
+    def _serializable_list(self, node_id, username, moderator):
+        session = Session()
+
+        if username:
+            # If a username is provided, create a subquery to retrieve all
+            # votes by this user. We will outerjoin with the comment query
+            # with this subquery so we have a user's voting information.
+            sq = session.query(CommentVote).\
+                filter(CommentVote.username == username).subquery()
+            cvalias = aliased(CommentVote, sq)
+            q = session.query(Comment, cvalias.value).outerjoin(cvalias)
+        else:
+            q = session.query(Comment)
+
+        # Filter out all comments not descending from this node.
+        q = q.filter(Comment.path.like(node_id + '.%'))
+        # Filter out non-displayed comments if this isn't a moderator.
+        if not moderator:
+            q = q.filter(Comment.displayed == True)
+        # Retrieve all results. Results must be ordered by Comment.path
+        # so that we can easily transform them from a flat list to a tree.
+        results = q.order_by(Comment.path).all()
+        session.close()
+
+        # We now need to convert the flat list of results to a nested
+        # lists to form the comment tree. Results will by ordered by
+        # the materialized path.
+        comments = []
+        list_stack = [comments]
+        for r in results:
+            comment, vote = r if username else (r, 0)
+
+            inheritance_chain = comment.path.split('.')[1:]
+            
+            if len(inheritance_chain) == len(list_stack) + 1:
+                parent = list_stack[-1][-1]
+                list_stack.append(parent['children'])
+            elif len(inheritance_chain) < len(list_stack):
+                while len(inheritance_chain) < len(list_stack):
+                    list_stack.pop()
+
+            list_stack[-1].append(comment.serializable(vote=vote))
+        
+        return comments
+
+    def process_vote(self, comment_id, username, value):
         session = Session()
         vote = session.query(CommentVote).filter(
             CommentVote.comment_id == comment_id).filter(
-            CommentVote.user_id == user_id).first()
+            CommentVote.username == username).first()
 
         comment = session.query(Comment).filter(
             Comment.id == comment_id).first()
 
         if vote is None:
-            vote = CommentVote(comment_id, user_id, value)
+            vote = CommentVote(comment_id, username, value)
             comment.rating += value
         else:
             comment.rating += value - vote.value
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 53307fb4e..f92dbcdee 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -36,6 +36,7 @@ def clear_builddir():
 
 
 def teardown_module():
+    (test_root / 'generated').rmtree(True)
     clear_builddir()
 
 
@@ -130,13 +131,61 @@ def test_whoosh():
 @with_support()
 def test_comments(support):
     session = Session()
-    node = session.query(Node).first()
-    comment = support.add_comment('First test comment', node=str(node.id))
-    support.add_comment('Child test comment', parent=str(comment['id']))
-    data = support.get_comments(str(node.id))
+    nodes = session.query(Node).all()
+    first_node = nodes[0]
+    second_node = nodes[1]
+
+    # Create a displayed comment and a non displayed comment.
+    comment = support.add_comment('First test comment', 
+                                  node_id=str(first_node.id))
+    support.add_comment('Hidden comment', node_id=str(first_node.id), 
+                        displayed=False)
+    # Add a displayed and not displayed child to the displayed comment.
+    support.add_comment('Child test comment', parent_id=str(comment['id']))
+    support.add_comment('Hidden child test comment', 
+                        parent_id=str(comment['id']), displayed=False)
+    # Add a comment to another node to make sure it isn't returned later.
+    support.add_comment('Second test comment', 
+                        node_id=str(second_node.id))
+    
+    # Access the comments as a moderator.
+    data = support.get_comments(str(first_node.id), moderator=True)
+    comments = data['comments']
+    children = comments[0]['children']
+    assert len(comments) == 2
+    assert comments[1]['text'] == 'Hidden comment'
+    assert len(children) == 2
+    assert children[1]['text'] == 'Hidden child test comment'
+
+    # Access the comments without being a moderator.
+    data = support.get_comments(str(first_node.id))
     comments = data['comments']
     children = comments[0]['children']
     assert len(comments) == 1
     assert comments[0]['text'] == 'First test comment'
     assert len(children) == 1
     assert children[0]['text'] == 'Child test comment'
+
+    def check_rating(val):
+        data = support.get_comments(str(first_node.id))
+        comment = data['comments'][0]
+        assert comment['rating'] == val, '%s != %s' % (comment['rating'], val)
+        
+    support.process_vote(comment['id'], 'user_one', '1')
+    support.process_vote(comment['id'], 'user_two', '1')
+    support.process_vote(comment['id'], 'user_three', '1')
+    check_rating(3)
+    support.process_vote(comment['id'], 'user_one', '-1')
+    check_rating(1)
+    support.process_vote(comment['id'], 'user_one', '0')
+    check_rating(2)
+
+    # Make sure a vote with value > 1 or < -1 can't be cast.
+    raises(ValueError, support.process_vote, comment['id'], 'user_one', '2')
+    raises(ValueError, support.process_vote, comment['id'], 'user_one', '-2')
+
+    # Make sure past voting data is associated with comments when they are
+    # fetched.
+    data = support.get_comments(str(first_node.id), username='user_two')
+    comment = data['comments'][0]
+    assert comment['vote'] == 1, '%s != 1' % comment['vote']

From 248c01af3ec09ce34bb39ef43605c2ce37896bd8 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Wed, 4 Aug 2010 11:25:30 -0500
Subject: [PATCH 064/127] Separate search adapter tests from others

---
 tests/test_searchadapters.py | 82 ++++++++++++++++++++++++++++++++++++
 tests/test_websupport.py     | 74 +++-----------------------------
 2 files changed, 88 insertions(+), 68 deletions(-)
 create mode 100644 tests/test_searchadapters.py

diff --git a/tests/test_searchadapters.py b/tests/test_searchadapters.py
new file mode 100644
index 000000000..94f72cab4
--- /dev/null
+++ b/tests/test_searchadapters.py
@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+"""
+    test_searchadapters
+    ~~~~~~~~~~~~~~~~~~~
+
+    Test the Web Support Package search adapters.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import os
+from StringIO import StringIO
+
+from util import *
+from sphinx.websupport import WebSupport
+
+
+def clear_builddir():
+    (test_root / 'websupport').rmtree(True)
+
+
+def teardown_module():
+    (test_root / 'generated').rmtree(True)
+    clear_builddir()
+
+
+def search_adapter_helper(adapter):
+    clear_builddir()
+    
+    settings = {'outdir': os.path.join(test_root, 'websupport'),
+                'status': StringIO(),
+                'warning': StringIO()}
+    settings.update({'srcdir': test_root,
+                     'search': adapter})
+    support = WebSupport(**settings)
+    support.build()
+
+    s = support.search
+
+    # Test the adapters query method. A search for "Epigraph" should return
+    # one result.
+    results = s.query(u'Epigraph')
+    assert len(results) == 1, \
+        '%s search adapter returned %s search result(s), should have been 1'\
+        % (adapter, len(results))
+
+    # Make sure documents are properly updated by the search adapter.
+    s.init_indexing(changed=['markup'])
+    s.add_document(u'markup', u'title', u'SomeLongRandomWord')
+    s.finish_indexing()
+    # Now a search for "Epigraph" should return zero results.
+    results = s.query(u'Epigraph')
+    assert len(results) == 0, \
+        '%s search adapter returned %s search result(s), should have been 0'\
+        % (adapter, len(results))
+    # A search for "SomeLongRandomWord" should return one result.
+    results = s.query(u'SomeLongRandomWord')
+    assert len(results) == 1, \
+        '%s search adapter returned %s search result(s), should have been 1'\
+        % (adapter, len(results))
+    
+
+def test_xapian():
+    # Don't run tests if xapian is not installed.
+    try:
+        import xapian
+        search_adapter_helper('xapian')
+    except ImportError:
+        sys.stderr.write('info: not running xapian tests, ' \
+                         'xapian doesn\'t seem to be installed')
+
+
+def test_whoosh():
+    # Don't run tests if whoosh is not installed.
+    try:
+        import whoosh
+        search_adapter_helper('whoosh')
+    except ImportError:
+        sys.stderr.write('info: not running whoosh tests, ' \
+                         'whoosh doesn\'t seem to be installed')
+
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index f92dbcdee..5e0326047 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -9,13 +9,14 @@
     :license: BSD, see LICENSE for details.
 """
 
-import os, sys
+import os
 from StringIO import StringIO
 
 from sphinx.websupport import WebSupport
 from sphinx.websupport.errors import *
 from sphinx.websupport.comments.sqlalchemystorage import Session
 from sphinx.websupport.comments.db import Node
+from util import *
 
 try:
     from functools import wraps
@@ -23,26 +24,17 @@ except ImportError:
     # functools is new in 2.4
     wraps = lambda f: (lambda w: w)
 
-from util import *
-
-
-default_settings = {'outdir': os.path.join(test_root, 'websupport'),
-                    'status': StringIO(),
-                    'warning': StringIO()}
-
-
-def clear_builddir():
-    (test_root / 'websupport').rmtree(True)
-
 
 def teardown_module():
     (test_root / 'generated').rmtree(True)
-    clear_builddir()
+    (test_root / 'websupport').rmtree(True)
 
 
 def with_support(*args, **kwargs):
     """Make a WebSupport object and pass it the test."""
-    settings = default_settings.copy()
+    settings = {'outdir': os.path.join(test_root, 'websupport'),
+                'status': StringIO(),
+                'warning': StringIO()}
     settings.update(kwargs)
 
     def generator(func):
@@ -74,60 +66,6 @@ def test_get_document(support):
         and contents['sidebar'] and contents['relbar']
 
 
-def search_adapter_helper(adapter):
-    clear_builddir()
-    
-    settings = default_settings.copy()
-    settings.update({'srcdir': test_root,
-                     'search': adapter})
-    support = WebSupport(**settings)
-    support.build()
-
-    s = support.search
-
-    # Test the adapters query method. A search for "Epigraph" should return
-    # one result.
-    results = s.query(u'Epigraph')
-    assert len(results) == 1, \
-        '%s search adapter returned %s search result(s), should have been 1'\
-        % (adapter, len(results))
-
-    # Make sure documents are properly updated by the search adapter.
-    s.init_indexing(changed=['markup'])
-    s.add_document(u'markup', u'title', u'SomeLongRandomWord')
-    s.finish_indexing()
-    # Now a search for "Epigraph" should return zero results.
-    results = s.query(u'Epigraph')
-    assert len(results) == 0, \
-        '%s search adapter returned %s search result(s), should have been 0'\
-        % (adapter, len(results))
-    # A search for "SomeLongRandomWord" should return one result.
-    results = s.query(u'SomeLongRandomWord')
-    assert len(results) == 1, \
-        '%s search adapter returned %s search result(s), should have been 1'\
-        % (adapter, len(results))
-    
-
-def test_xapian():
-    # Don't run tests if xapian is not installed.
-    try:
-        import xapian
-        search_adapter_helper('xapian')
-    except ImportError:
-        sys.stderr.write('info: not running xapian tests, ' \
-                         'xapian doesn\'t seem to be installed')
-
-
-def test_whoosh():
-    # Don't run tests if whoosh is not installed.
-    try:
-        import whoosh
-        search_adapter_helper('whoosh')
-    except ImportError:
-        sys.stderr.write('info: not running whoosh tests, ' \
-                         'whoosh doesn\'t seem to be installed')
-
-
 @with_support()
 def test_comments(support):
     session = Session()

From 75ae087f7aece6b81c20a37641b363dc23ad5e83 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Wed, 4 Aug 2010 13:09:07 -0500
Subject: [PATCH 065/127] added more test coverage.

---
 sphinx/websupport/comments/differ.py          |  4 +-
 .../websupport/comments/sqlalchemystorage.py  |  1 +
 tests/test_searchadapters.py                  |  4 +-
 tests/test_websupport.py                      | 48 ++++++++++++++++---
 4 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/sphinx/websupport/comments/differ.py b/sphinx/websupport/comments/differ.py
index 786922346..2ecacea58 100644
--- a/sphinx/websupport/comments/differ.py
+++ b/sphinx/websupport/comments/differ.py
@@ -21,7 +21,7 @@ class CombinedHtmlDiff(object):
         next = next[2:]
         new_text = []
         start = 0
-        for match in highlight_regex.finditer(next):
+        for match in self.highlight_regex.finditer(next):
             new_text.append(text[start:match.start()])
             new_text.append('<%s>' % tag)
             new_text.append(text[match.start():match.end()])
@@ -30,7 +30,7 @@ class CombinedHtmlDiff(object):
         new_text.append(text[start:])
         return ''.join(new_text)
 
-    def _handle_line(line, next=None):
+    def _handle_line(self, line, next=None):
         prefix = line[0]
         text = line[2:]
 
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 0e11c4a09..63db1550e 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -42,6 +42,7 @@ class SQLAlchemyStorage(StorageBackend):
         session = Session()
         
         if node_id and proposal:
+            node = session.query(Node).filter(Node.id == node_id).one()
             differ = CombinedHtmlDiff()
             proposal_diff = differ.make_html(node.source, proposal)
         else:
diff --git a/tests/test_searchadapters.py b/tests/test_searchadapters.py
index 94f72cab4..186b2e429 100644
--- a/tests/test_searchadapters.py
+++ b/tests/test_searchadapters.py
@@ -59,7 +59,9 @@ def search_adapter_helper(adapter):
     assert len(results) == 1, \
         '%s search adapter returned %s search result(s), should have been 1'\
         % (adapter, len(results))
-    
+    # Make sure it works through the WebSupport API
+    html = support.get_search_results(u'SomeLongRandomWord')
+
 
 def test_xapian():
     # Don't run tests if xapian is not installed.
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 5e0326047..464c8c74b 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -14,7 +14,9 @@ from StringIO import StringIO
 
 from sphinx.websupport import WebSupport
 from sphinx.websupport.errors import *
-from sphinx.websupport.comments.sqlalchemystorage import Session
+from sphinx.websupport.comments.differ import CombinedHtmlDiff
+from sphinx.websupport.comments.sqlalchemystorage import Session, \
+    SQLAlchemyStorage
 from sphinx.websupport.comments.db import Node
 from util import *
 
@@ -25,6 +27,10 @@ except ImportError:
     wraps = lambda f: (lambda w: w)
 
 
+default_settings = {'outdir': os.path.join(test_root, 'websupport'),
+                    'status': StringIO(),
+                    'warning': StringIO()}
+
 def teardown_module():
     (test_root / 'generated').rmtree(True)
     (test_root / 'websupport').rmtree(True)
@@ -32,9 +38,7 @@ def teardown_module():
 
 def with_support(*args, **kwargs):
     """Make a WebSupport object and pass it the test."""
-    settings = {'outdir': os.path.join(test_root, 'websupport'),
-                'status': StringIO(),
-                'warning': StringIO()}
+    settings = default_settings.copy()
     settings.update(kwargs)
 
     def generator(func):
@@ -104,8 +108,17 @@ def test_comments(support):
     assert len(children) == 1
     assert children[0]['text'] == 'Child test comment'
 
+
+@with_support()
+def test_voting(support):
+    session = Session()
+    nodes = session.query(Node).all()
+    node = nodes[0]
+
+    comment = support.get_comments(str(node.id))['comments'][0]
+
     def check_rating(val):
-        data = support.get_comments(str(first_node.id))
+        data = support.get_comments(str(node.id))
         comment = data['comments'][0]
         assert comment['rating'] == val, '%s != %s' % (comment['rating'], val)
         
@@ -124,6 +137,29 @@ def test_comments(support):
 
     # Make sure past voting data is associated with comments when they are
     # fetched.
-    data = support.get_comments(str(first_node.id), username='user_two')
+    data = support.get_comments(str(node.id), username='user_two')
     comment = data['comments'][0]
     assert comment['vote'] == 1, '%s != 1' % comment['vote']
+
+@with_support()
+def test_proposals(support):
+    session = Session()
+    nodes = session.query(Node).all()
+    node = nodes[0]
+
+    data = support.get_comments(str(node.id))
+
+    source = data['source']
+    proposal = source[:5] + source[10:15] + 'asdf' + source[15:]
+
+    comment = support.add_comment('Proposal comment', 
+                                  node_id=str(node.id),
+                                  proposal=proposal)
+
+def test_differ():
+    differ = CombinedHtmlDiff()
+    source = 'Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\n' \
+        'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.' 
+    prop = 'Lorem dolor sit amet,\nconsectetur nihil adipisicing elit,\n' \
+        'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
+    differ.make_html(source, prop)

From 338c349dd526d1a51eef4f6aaeacb09c333eee80 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Wed, 4 Aug 2010 13:12:57 -0500
Subject: [PATCH 066/127] renamed get_comments get_data

---
 sphinx/websupport/__init__.py                   |  4 ++--
 sphinx/websupport/comments/sqlalchemystorage.py |  2 +-
 tests/test_websupport.py                        | 12 ++++++------
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 373622eb1..8bc2a0b8b 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -157,7 +157,7 @@ class WebSupport(object):
         document['title'] = 'Search Results'
         return document
 
-    def get_comments(self, node_id, username=None, moderator=False):
+    def get_data(self, node_id, username=None, moderator=False):
         """Get the comments and source associated with `node_id`. If 
         `user_id` is given vote information will be included with the 
         returned comments. The default CommentBackend returns dict with
@@ -191,7 +191,7 @@ class WebSupport(object):
         :param node_id: the id of the node to get comments for.
         :param user_id: the id of the user viewing the comments.
         """
-        return self.storage.get_comments(node_id, username, moderator)
+        return self.storage.get_data(node_id, username, moderator)
 
     def add_comment(self, text, node_id='', parent_id='', displayed=True, 
                     username=None, rating=0, time=None, proposal=None,
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/comments/sqlalchemystorage.py
index 63db1550e..085913fdf 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/comments/sqlalchemystorage.py
@@ -58,7 +58,7 @@ class SQLAlchemyStorage(StorageBackend):
         session.close()
         return comment
 
-    def get_comments(self, node_id, username, moderator):
+    def get_data(self, node_id, username, moderator):
         session = Session()
         node = session.query(Node).filter(Node.id == node_id).one()
         session.close()
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 464c8c74b..8f701cd2a 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -91,7 +91,7 @@ def test_comments(support):
                         node_id=str(second_node.id))
     
     # Access the comments as a moderator.
-    data = support.get_comments(str(first_node.id), moderator=True)
+    data = support.get_data(str(first_node.id), moderator=True)
     comments = data['comments']
     children = comments[0]['children']
     assert len(comments) == 2
@@ -100,7 +100,7 @@ def test_comments(support):
     assert children[1]['text'] == 'Hidden child test comment'
 
     # Access the comments without being a moderator.
-    data = support.get_comments(str(first_node.id))
+    data = support.get_data(str(first_node.id))
     comments = data['comments']
     children = comments[0]['children']
     assert len(comments) == 1
@@ -115,10 +115,10 @@ def test_voting(support):
     nodes = session.query(Node).all()
     node = nodes[0]
 
-    comment = support.get_comments(str(node.id))['comments'][0]
+    comment = support.get_data(str(node.id))['comments'][0]
 
     def check_rating(val):
-        data = support.get_comments(str(node.id))
+        data = support.get_data(str(node.id))
         comment = data['comments'][0]
         assert comment['rating'] == val, '%s != %s' % (comment['rating'], val)
         
@@ -137,7 +137,7 @@ def test_voting(support):
 
     # Make sure past voting data is associated with comments when they are
     # fetched.
-    data = support.get_comments(str(node.id), username='user_two')
+    data = support.get_data(str(node.id), username='user_two')
     comment = data['comments'][0]
     assert comment['vote'] == 1, '%s != 1' % comment['vote']
 
@@ -147,7 +147,7 @@ def test_proposals(support):
     nodes = session.query(Node).all()
     node = nodes[0]
 
-    data = support.get_comments(str(node.id))
+    data = support.get_data(str(node.id))
 
     source = data['source']
     proposal = source[:5] + source[10:15] + 'asdf' + source[15:]

From a08651e6d0fe539e1bed554cfec3c6c545c5357e Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Wed, 4 Aug 2010 13:20:43 -0500
Subject: [PATCH 067/127] rename comments package storage

---
 sphinx/websupport/__init__.py | 4 ++--
 tests/test_searchadapters.py  | 2 +-
 tests/test_websupport.py      | 6 +++---
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 8bc2a0b8b..4f469a4a2 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -19,7 +19,7 @@ from jinja2 import Environment, FileSystemLoader
 from sphinx.application import Sphinx
 from sphinx.util.osutil import ensuredir
 from sphinx.websupport.search import BaseSearch, search_adapters
-from sphinx.websupport.comments import StorageBackend
+from sphinx.websupport.storage import StorageBackend
 from sphinx.websupport.errors import *
 
 class WebSupportApp(Sphinx):
@@ -54,7 +54,7 @@ class WebSupport(object):
         else:
             # If a StorageBackend isn't provided, use the default
             # SQLAlchemy backend with an SQLite db.
-            from sphinx.websupport.comments.sqlalchemystorage \
+            from sphinx.websupport.storage.sqlalchemystorage \
                 import SQLAlchemyStorage
             from sqlalchemy import create_engine
             db_path = path.join(self.outdir, 'db', 'websupport.db')
diff --git a/tests/test_searchadapters.py b/tests/test_searchadapters.py
index 186b2e429..c9525f758 100644
--- a/tests/test_searchadapters.py
+++ b/tests/test_searchadapters.py
@@ -9,7 +9,7 @@
     :license: BSD, see LICENSE for details.
 """
 
-import os
+import os, sys
 from StringIO import StringIO
 
 from util import *
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 8f701cd2a..bfa07226f 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -14,10 +14,10 @@ from StringIO import StringIO
 
 from sphinx.websupport import WebSupport
 from sphinx.websupport.errors import *
-from sphinx.websupport.comments.differ import CombinedHtmlDiff
-from sphinx.websupport.comments.sqlalchemystorage import Session, \
+from sphinx.websupport.storage.differ import CombinedHtmlDiff
+from sphinx.websupport.storage.sqlalchemystorage import Session, \
     SQLAlchemyStorage
-from sphinx.websupport.comments.db import Node
+from sphinx.websupport.storage.db import Node
 from util import *
 
 try:

From f58fe6eed69a40c962bac57e672ec0d41b4a714c Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Wed, 4 Aug 2010 14:28:30 -0500
Subject: [PATCH 068/127] allow custom db uris for sqlalchemybackend

---
 sphinx/websupport/__init__.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 4f469a4a2..b5cea0212 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -32,7 +32,6 @@ class WebSupport(object):
     """The main API class for the web support package. All interactions
     with the web support package should occur through this class.
     """
-
     def __init__(self, srcdir='', outdir='', datadir='', search=None,
                  storage=None, status=sys.stdout, warning=sys.stderr):
         self.srcdir = srcdir
@@ -53,13 +52,14 @@ class WebSupport(object):
             self.storage = storage
         else:
             # If a StorageBackend isn't provided, use the default
-            # SQLAlchemy backend with an SQLite db.
+            # SQLAlchemy backend.
             from sphinx.websupport.storage.sqlalchemystorage \
                 import SQLAlchemyStorage
             from sqlalchemy import create_engine
             db_path = path.join(self.outdir, 'db', 'websupport.db')
             ensuredir(path.dirname(db_path))
-            engine = create_engine('sqlite:///%s' % db_path)
+            uri = storage or 'sqlite:///%s' % db_path
+            engine = create_engine(uri)
             self.storage = SQLAlchemyStorage(engine)
 
     def _init_templating(self):

From 69a2c07396f94ec0099c24089dd452b30cc06052 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Wed, 4 Aug 2010 16:06:10 -0500
Subject: [PATCH 069/127] added delete_comment method

---
 sphinx/websupport/__init__.py | 19 +++++++++++++--
 sphinx/websupport/errors.py   |  7 +++++-
 tests/test_websupport.py      | 46 ++++++++++++++++++++++++++++++++---
 3 files changed, 65 insertions(+), 7 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index b5cea0212..03b9c8e8b 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -85,7 +85,7 @@ class WebSupport(object):
         """Build the documentation. Places the data into the `outdir`
         directory. Use it like this::
 
-            support = WebSupport(srcdir, outdir, search)
+            support = WebSupport(srcdir, outdir, search='xapian')
             support.build()
 
         This will read reStructured text files from `srcdir`. Then it
@@ -109,7 +109,7 @@ class WebSupport(object):
         """Load and return a document from a pickle. The document will
         be a dict object which can be used to render a template::
 
-            support = WebSupport(outdir=outdir)
+            support = WebSupport(datadir=datadir)
             support.get_document('index')
             
         In most cases `docname` will be taken from the request path and 
@@ -193,6 +193,21 @@ class WebSupport(object):
         """
         return self.storage.get_data(node_id, username, moderator)
 
+    def delete_comment(self, comment_id, username='', moderator=False):
+        """Delete a comment. Doesn't actually delete the comment, but
+        instead replaces the username and text files with "[deleted]" so
+        as not to leave any comments orphaned.
+
+        If `moderator` is True, the comment will always be deleted. If 
+        `moderator` is False, the comment will only be deleted if the
+        `username` matches the `username` on the comment.
+
+        :param comment_id: the id of the comment to delete.
+        :param username: the username requesting the deletion.
+        :param moderator: whether the requestor is a moderator.
+        """
+        self.storage.delete_comment(comment_id, username, moderator)
+
     def add_comment(self, text, node_id='', parent_id='', displayed=True, 
                     username=None, rating=0, time=None, proposal=None,
                     moderator=False):
diff --git a/sphinx/websupport/errors.py b/sphinx/websupport/errors.py
index b1c47915e..fbb75a93d 100644
--- a/sphinx/websupport/errors.py
+++ b/sphinx/websupport/errors.py
@@ -9,7 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
-__all__ = ['DocumentNotFoundError', 'SrcdirNotSpecifiedError']
+__all__ = ['DocumentNotFoundError', 'SrcdirNotSpecifiedError',
+           'UserNotAuthorizedError']
 
 class DocumentNotFoundError(Exception):
     pass
@@ -17,3 +18,7 @@ class DocumentNotFoundError(Exception):
 
 class SrcdirNotSpecifiedError(Exception):
     pass
+
+
+class UserNotAuthorizedError(Exception):
+    pass
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index bfa07226f..ca64ec2d1 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -79,11 +79,13 @@ def test_comments(support):
 
     # Create a displayed comment and a non displayed comment.
     comment = support.add_comment('First test comment', 
-                                  node_id=str(first_node.id))
+                                  node_id=str(first_node.id),
+                                  username='user_one')
     support.add_comment('Hidden comment', node_id=str(first_node.id), 
                         displayed=False)
     # Add a displayed and not displayed child to the displayed comment.
-    support.add_comment('Child test comment', parent_id=str(comment['id']))
+    support.add_comment('Child test comment', parent_id=str(comment['id']),
+                        username='user_one')
     support.add_comment('Hidden child test comment', 
                         parent_id=str(comment['id']), displayed=False)
     # Add a comment to another node to make sure it isn't returned later.
@@ -144,8 +146,7 @@ def test_voting(support):
 @with_support()
 def test_proposals(support):
     session = Session()
-    nodes = session.query(Node).all()
-    node = nodes[0]
+    node = session.query(Node).first()
 
     data = support.get_data(str(node.id))
 
@@ -156,6 +157,43 @@ def test_proposals(support):
                                   node_id=str(node.id),
                                   proposal=proposal)
 
+
+@with_support()
+def test_user_delete_comments(support):
+    def get_comment():
+        session = Session()
+        node = session.query(Node).first()
+        session.close()
+        return support.get_data(str(node.id))['comments'][0]
+
+    comment = get_comment()
+    assert comment['username'] == 'user_one'
+    # Make sure other normal users can't delete someone elses comments.
+    raises(UserNotAuthorizedError, support.delete_comment,
+           comment['id'], username='user_two')
+    # Now delete the comment using the correct username.
+    support.delete_comment(comment['id'], username='user_one')
+    comment = get_comment()
+    assert comment['username'] == '[deleted]'
+    assert comment['text'] == '[deleted]'
+
+
+@with_support()
+def test_moderator_delete_comments(support):
+    def get_comment():
+        session = Session()
+        node = session.query(Node).first()
+        session.close()
+        return support.get_data(str(node.id), moderator=True)['comments'][1]
+
+    comment = get_comment()
+    support.delete_comment(comment['id'], username='user_two', 
+                           moderator=True)
+    comment = get_comment()
+    assert comment['username'] == '[deleted]'
+    assert comment['text'] == '[deleted]'
+
+
 def test_differ():
     differ = CombinedHtmlDiff()
     source = 'Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\n' \

From 790715d37b1247a606437392a65711187885b34a Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 5 Aug 2010 12:20:15 -0500
Subject: [PATCH 070/127] added update_username method

---
 sphinx/websupport/__init__.py | 13 +++++++++++++
 tests/test_websupport.py      | 22 ++++++++++++++++++++--
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 03b9c8e8b..f137ce2c3 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -268,3 +268,16 @@ class WebSupport(object):
         if not -1 <= value <= 1:
             raise ValueError('vote value %s out of range (-1, 1)' % value)
         self.storage.process_vote(comment_id, username, value)
+
+    def update_username(self, old_username, new_username):
+        """To remain decoupled from a webapp's authentication system, the
+        web support package stores a user's username with each of their
+        comments and votes. If the authentication system allows a user to
+        change their username, this can lead to stagnate data in the web
+        support system. To avoid this, each time a username is changed, this
+        method should be called.
+
+        :param old_username: The original username.
+        :param new_username: The new username.
+        """
+        self.storage.update_username(old_username, new_username)
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index ca64ec2d1..d0956916d 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -16,7 +16,7 @@ from sphinx.websupport import WebSupport
 from sphinx.websupport.errors import *
 from sphinx.websupport.storage.differ import CombinedHtmlDiff
 from sphinx.websupport.storage.sqlalchemystorage import Session, \
-    SQLAlchemyStorage
+    SQLAlchemyStorage, Comment, CommentVote
 from sphinx.websupport.storage.db import Node
 from util import *
 
@@ -90,7 +90,8 @@ def test_comments(support):
                         parent_id=str(comment['id']), displayed=False)
     # Add a comment to another node to make sure it isn't returned later.
     support.add_comment('Second test comment', 
-                        node_id=str(second_node.id))
+                        node_id=str(second_node.id),
+                        username='user_two')
     
     # Access the comments as a moderator.
     data = support.get_data(str(first_node.id), moderator=True)
@@ -193,6 +194,23 @@ def test_moderator_delete_comments(support):
     assert comment['username'] == '[deleted]'
     assert comment['text'] == '[deleted]'
 
+@with_support()
+def test_update_username(support):
+    support.update_username('user_two', 'new_user_two')
+    session = Session()
+    comments = session.query(Comment).\
+        filter(Comment.username == 'user_two').all()
+    assert len(comments) == 0
+    votes = session.query(CommentVote).\
+        filter(CommentVote.username == 'user_two')
+    assert len(comments) == 0
+    comments = session.query(Comment).\
+        filter(Comment.username == 'new_user_two').all()
+    assert len(comments) == 1
+    votes = session.query(CommentVote).\
+        filter(CommentVote.username == 'new_user_two')
+    assert len(comments) == 1
+
 
 def test_differ():
     differ = CombinedHtmlDiff()

From d0e272e61f34364f5cf9345363d5680f041fdf8f Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 5 Aug 2010 14:13:50 -0500
Subject: [PATCH 071/127] Add comment moderation backend

---
 sphinx/websupport/__init__.py | 27 +++++++++++++++++++++++----
 tests/test_websupport.py      | 23 +++++++++++++++++++++++
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index f137ce2c3..e04e6899b 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -33,10 +33,12 @@ class WebSupport(object):
     with the web support package should occur through this class.
     """
     def __init__(self, srcdir='', outdir='', datadir='', search=None,
-                 storage=None, status=sys.stdout, warning=sys.stderr):
+                 storage=None, status=sys.stdout, warning=sys.stderr,
+                 moderation_callback=None):
         self.srcdir = srcdir
         self.outdir = outdir or path.join(self.srcdir, '_build',
                                           'websupport')
+        self.moderation_callback = moderation_callback
         self._init_templating()
 
         self.outdir = outdir or datadir
@@ -236,9 +238,12 @@ class WebSupport(object):
         :param rating: the starting rating of the comment, defaults to 0.
         :param time: the time the comment was created, defaults to now.
         """
-        return self.storage.add_comment(text, displayed, username, rating,
-                                        time, proposal, node_id, parent_id, 
-                                        moderator)
+        comment = self.storage.add_comment(text, displayed, username, rating,
+                                           time, proposal, node_id, 
+                                           parent_id, moderator)
+        if not displayed and self.moderation_callback:
+            self.moderation_callback(comment)
+        return comment
 
     def process_vote(self, comment_id, username, value):
         """Process a user's vote. The web support package relies
@@ -281,3 +286,17 @@ class WebSupport(object):
         :param new_username: The new username.
         """
         self.storage.update_username(old_username, new_username)
+
+    def accept_comment(self, comment_id):
+        """Accept a comment that is pending moderation.
+
+        :param comment_id: The id of the comment that was accepted.
+        """
+        self.storage.accept_comment(comment_id)
+
+    def reject_comment(self, comment_id):
+        """Reject a comment that is pending moderation.
+
+        :param comment_id: The id of the comment that was accepted.
+        """
+        self.storage.reject_comment(comment_id)
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index d0956916d..e9c68cf63 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -194,6 +194,7 @@ def test_moderator_delete_comments(support):
     assert comment['username'] == '[deleted]'
     assert comment['text'] == '[deleted]'
 
+
 @with_support()
 def test_update_username(support):
     support.update_username('user_two', 'new_user_two')
@@ -212,6 +213,28 @@ def test_update_username(support):
     assert len(comments) == 1
 
 
+called = False
+def moderation_callback(comment):
+    global called
+    called = True
+
+
+@with_support(moderation_callback=moderation_callback)
+def test_moderation(support):
+    accepted = support.add_comment('Accepted Comment', node_id=3, 
+                                   displayed=False)
+    rejected = support.add_comment('Rejected comment', node_id=3, 
+                                   displayed=False)
+    # Make sure the moderation_callback is called.
+    assert called == True
+    support.accept_comment(accepted['id'])
+    support.reject_comment(rejected['id'])
+    comments = support.get_data(3)['comments']
+    assert len(comments) == 1
+    comments = support.get_data(3, moderator=True)['comments']
+    assert len(comments) == 1
+
+
 def test_differ():
     differ = CombinedHtmlDiff()
     source = 'Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\n' \

From fbd047b8f593a439d0a8ca9eec02ad2491d2bd78 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 5 Aug 2010 15:01:13 -0500
Subject: [PATCH 072/127] Ensure hidden comments can't be replied to

---
 sphinx/websupport/errors.py |  6 +++++-
 tests/test_websupport.py    | 11 +++++++++--
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/sphinx/websupport/errors.py b/sphinx/websupport/errors.py
index fbb75a93d..e78abc217 100644
--- a/sphinx/websupport/errors.py
+++ b/sphinx/websupport/errors.py
@@ -10,7 +10,7 @@
 """
 
 __all__ = ['DocumentNotFoundError', 'SrcdirNotSpecifiedError',
-           'UserNotAuthorizedError']
+           'UserNotAuthorizedError', 'CommentNotAllowedError']
 
 class DocumentNotFoundError(Exception):
     pass
@@ -22,3 +22,7 @@ class SrcdirNotSpecifiedError(Exception):
 
 class UserNotAuthorizedError(Exception):
     pass
+
+
+class CommentNotAllowedError(Exception):
+    pass
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index e9c68cf63..2db29a2e1 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -81,8 +81,14 @@ def test_comments(support):
     comment = support.add_comment('First test comment', 
                                   node_id=str(first_node.id),
                                   username='user_one')
-    support.add_comment('Hidden comment', node_id=str(first_node.id), 
-                        displayed=False)
+    hidden_comment = support.add_comment('Hidden comment', 
+                                         node_id=str(first_node.id), 
+                                         displayed=False)
+    # Make sure that comments can't be added to a comment where
+    # displayed == False, since it could break the algorithm that
+    # converts a nodes comments to a tree.
+    raises(CommentNotAllowedError, support.add_comment, 'Not allowed', 
+           parent_id=str(hidden_comment['id']))
     # Add a displayed and not displayed child to the displayed comment.
     support.add_comment('Child test comment', parent_id=str(comment['id']),
                         username='user_one')
@@ -144,6 +150,7 @@ def test_voting(support):
     comment = data['comments'][0]
     assert comment['vote'] == 1, '%s != 1' % comment['vote']
 
+
 @with_support()
 def test_proposals(support):
     session = Session()

From d29f65112e327054dde4501a61d3c7d4fa16bcbf Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 5 Aug 2010 19:29:24 -0500
Subject: [PATCH 073/127] added storage package

---
 .../{comments => storage}/__init__.py         |  8 +--
 sphinx/websupport/{comments => storage}/db.py |  4 +-
 .../{comments => storage}/differ.py           |  4 +-
 .../sqlalchemystorage.py                      | 61 ++++++++++++++++---
 4 files changed, 62 insertions(+), 15 deletions(-)
 rename sphinx/websupport/{comments => storage}/__init__.py (88%)
 rename sphinx/websupport/{comments => storage}/db.py (98%)
 rename sphinx/websupport/{comments => storage}/differ.py (96%)
 rename sphinx/websupport/{comments => storage}/sqlalchemystorage.py (68%)

diff --git a/sphinx/websupport/comments/__init__.py b/sphinx/websupport/storage/__init__.py
similarity index 88%
rename from sphinx/websupport/comments/__init__.py
rename to sphinx/websupport/storage/__init__.py
index 10856dffd..6948c8c73 100644
--- a/sphinx/websupport/comments/__init__.py
+++ b/sphinx/websupport/storage/__init__.py
@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx.websupport.comments
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~
+    sphinx.websupport.storage
+    ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    Comments for the websupport package.
+    Storage for the websupport package.
 
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
@@ -40,7 +40,7 @@ class StorageBackend(object):
         """Called when a comment is being added."""
         raise NotImplementedError()
 
-    def get_comments(self, parent_id, user_id, moderator):
+    def get_data(self, parent_id, user_id, moderator):
         """Called to retrieve all comments for a node."""
         raise NotImplementedError()
 
diff --git a/sphinx/websupport/comments/db.py b/sphinx/websupport/storage/db.py
similarity index 98%
rename from sphinx/websupport/comments/db.py
rename to sphinx/websupport/storage/db.py
index 91175ed38..23b6a462c 100644
--- a/sphinx/websupport/comments/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx.websupport.comments.db
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    sphinx.websupport.storage.db
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
     SQLAlchemy table and mapper definitions used by the
     :class:`sphinx.websupport.comments.SQLAlchemyStorage`.
diff --git a/sphinx/websupport/comments/differ.py b/sphinx/websupport/storage/differ.py
similarity index 96%
rename from sphinx/websupport/comments/differ.py
rename to sphinx/websupport/storage/differ.py
index 2ecacea58..4e5660c59 100644
--- a/sphinx/websupport/comments/differ.py
+++ b/sphinx/websupport/storage/differ.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx.websupport.comments.differ
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    sphinx.websupport.storage.differ
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
     A differ for creating an HTML representations of proposal diffs
 
diff --git a/sphinx/websupport/comments/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
similarity index 68%
rename from sphinx/websupport/comments/sqlalchemystorage.py
rename to sphinx/websupport/storage/sqlalchemystorage.py
index 085913fdf..e96f38cf0 100644
--- a/sphinx/websupport/comments/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx.websupport.comments.sqlalchemystorage
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    sphinx.websupport.storage.sqlalchemystorage
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    A SQLAlchemy storage backend.
+    An SQLAlchemy storage backend.
 
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
@@ -12,10 +12,11 @@
 from datetime import datetime
 
 from sqlalchemy.orm import aliased
-from sphinx.websupport.comments import StorageBackend
-from sphinx.websupport.comments.db import Base, Node, Comment, CommentVote,\
+from sphinx.websupport.errors import *
+from sphinx.websupport.storage import StorageBackend
+from sphinx.websupport.storage.db import Base, Node, Comment, CommentVote,\
                                           Session
-from sphinx.websupport.comments.differ import CombinedHtmlDiff
+from sphinx.websupport.storage.differ import CombinedHtmlDiff
 
 class SQLAlchemyStorage(StorageBackend):
     def __init__(self, engine):
@@ -45,6 +46,13 @@ class SQLAlchemyStorage(StorageBackend):
             node = session.query(Node).filter(Node.id == node_id).one()
             differ = CombinedHtmlDiff()
             proposal_diff = differ.make_html(node.source, proposal)
+        elif parent_id:
+            parent = session.query(Comment.displayed).\
+                filter(Comment.id == parent_id).one()
+            if not parent.displayed:
+                raise CommentNotAllowedError(
+                    "Can't add child to a parent that is not displayed")
+            proposal_diff = None
         else:
             proposal_diff = None
 
@@ -58,6 +66,19 @@ class SQLAlchemyStorage(StorageBackend):
         session.close()
         return comment
 
+    def delete_comment(self, comment_id, username, moderator):
+        session = Session()
+        comment = session.query(Comment).\
+            filter(Comment.id == comment_id).one()
+        if moderator or comment.username == username:
+            comment.username = '[deleted]'
+            comment.text = '[deleted]'
+            session.commit()
+            session.close()
+        else:
+            session.close()
+            raise UserNotAuthorizedError()
+
     def get_data(self, node_id, username, moderator):
         session = Session()
         node = session.query(Node).filter(Node.id == node_id).one()
@@ -81,7 +102,7 @@ class SQLAlchemyStorage(StorageBackend):
             q = session.query(Comment)
 
         # Filter out all comments not descending from this node.
-        q = q.filter(Comment.path.like(node_id + '.%'))
+        q = q.filter(Comment.path.like(str(node_id) + '.%'))
         # Filter out non-displayed comments if this isn't a moderator.
         if not moderator:
             q = q.filter(Comment.displayed == True)
@@ -129,3 +150,29 @@ class SQLAlchemyStorage(StorageBackend):
         session.add(vote)
         session.commit()
         session.close()
+
+    def update_username(self, old_username, new_username):
+        session = Session()
+        session.query(Comment).filter(Comment.username == old_username).\
+            update({Comment.username: new_username})
+        session.query(CommentVote).\
+            filter(CommentVote.username == old_username).\
+            update({CommentVote.username: new_username})
+        session.commit()
+        session.close()
+
+    def accept_comment(self, comment_id):
+        session = Session()
+        comment = session.query(Comment).\
+            filter(Comment.id == comment_id).one()
+        comment.displayed = True
+        session.commit()
+        session.close()
+
+    def reject_comment(self, comment_id):
+        session = Session()
+        comment = session.query(Comment).\
+            filter(Comment.id == comment_id).one()
+        session.delete(comment)
+        session.commit()
+        session.close()

From ad9ebe38cc7f478349dfb5594c341dbcf0833507 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 6 Aug 2010 14:07:12 -0500
Subject: [PATCH 074/127] use static paths for static files and resources

---
 sphinx/builders/websupport.py | 37 +++++++++++++++++++++++++++++------
 sphinx/websupport/__init__.py | 17 ++++++++--------
 2 files changed, 39 insertions(+), 15 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 40901eef9..eeadfc231 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -11,6 +11,9 @@
 
 import cPickle as pickle
 from os import path
+import posixpath
+import shutil
+from docutils.io import StringOutput
 
 from sphinx.util.osutil import os_path, relative_uri, ensuredir, copyfile
 from sphinx.builders.html import StandaloneHTMLBuilder
@@ -29,7 +32,21 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     def write_doc(self, docname, doctree):
         # The translator needs the docname to generate ids.
         self.cur_docname = docname
-        StandaloneHTMLBuilder.write_doc(self, docname, doctree)
+        destination = StringOutput(encoding='utf-8')
+        doctree.settings = self.docsettings
+
+        self.secnumbers = self.env.toc_secnumbers.get(docname, {})
+        self.imgpath = '/' + posixpath.join(self.app.staticdir, '_images')
+        self.post_process_images(doctree)
+        self.dlpath = '/' + posixpath.join(self.app.staticdir, '_downloads')
+        self.docwriter.write(doctree, destination)
+        self.docwriter.assemble_parts()
+        body = self.docwriter.parts['fragment']
+        metatags = self.docwriter.clean_meta
+
+        ctx = self.get_doc_context(docname, body, metatags)
+        self.index_page(docname, doctree, ctx.get('title', ''))
+        self.handle_page(docname, ctx, event_arg=doctree)
 
     def get_target_uri(self, docname, typ=None):
         return docname
@@ -50,8 +67,9 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
                    baseuri=self.get_target_uri(pagename)):
             if not resource:
                 otheruri = self.get_target_uri(otheruri)
-            uri = relative_uri(baseuri, otheruri) or '#'
-            return uri
+                return relative_uri(baseuri, otheruri) or '#'
+            else:
+                return '/' + posixpath.join(self.app.staticdir, otheruri)
         ctx['pathto'] = pathto
         ctx['hasdoc'] = lambda name: name in self.env.all_docs
         ctx['encoding'] = encoding = self.config.html_output_encoding
@@ -74,7 +92,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
             doc_ctx['relbar'] = template_module.relbar()
 
         if not outfilename:
-            outfilename = path.join(self.outdir,
+            outfilename = path.join(self.outdir, 'pickles',
                                     os_path(pagename) + self.out_suffix)
 
         ensuredir(path.dirname(outfilename))
@@ -87,10 +105,17 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
         # if there is a source file, copy the source file for the
         # "show source" link
         if ctx.get('sourcename'):
-            source_name = path.join(self.outdir, '_sources',
-                                    os_path(ctx['sourcename']))
+            source_name = path.join(self.outdir, self.app.staticdir,
+                                    '_sources',  os_path(ctx['sourcename']))
             ensuredir(path.dirname(source_name))
             copyfile(self.env.doc2path(pagename), source_name)
 
+    def handle_finish(self):
+        StandaloneHTMLBuilder.handle_finish(self)
+        shutil.move(path.join(self.outdir, '_images'),
+                    path.join(self.outdir, self.app.staticdir, '_images'))
+        shutil.move(path.join(self.outdir, '_static'),
+                    path.join(self.outdir, self.app.staticdir, '_static'))
+
     def dump_search_index(self):
         self.indexer.finish_indexing()
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index e04e6899b..29a0b0eee 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -24,6 +24,7 @@ from sphinx.websupport.errors import *
 
 class WebSupportApp(Sphinx):
     def __init__(self, *args, **kwargs):
+        self.staticdir = kwargs.pop('staticdir', None)
         self.search = kwargs.pop('search', None)
         self.storage = kwargs.pop('storage', None)
         Sphinx.__init__(self, *args, **kwargs)
@@ -34,18 +35,15 @@ class WebSupport(object):
     """
     def __init__(self, srcdir='', outdir='', datadir='', search=None,
                  storage=None, status=sys.stdout, warning=sys.stderr,
-                 moderation_callback=None):
+                 moderation_callback=None, staticdir='static'):
         self.srcdir = srcdir
-        self.outdir = outdir or path.join(self.srcdir, '_build',
-                                          'websupport')
-        self.moderation_callback = moderation_callback
-        self._init_templating()
-
         self.outdir = outdir or datadir
-
+        self.staticdir = staticdir.strip('/')
         self.status = status
         self.warning = warning
+        self.moderation_callback = moderation_callback
 
+        self._init_templating()
         self._init_search(search)            
         self._init_storage(storage)
 
@@ -101,7 +99,8 @@ class WebSupport(object):
         app = WebSupportApp(self.srcdir, self.srcdir,
                             self.outdir, doctreedir, 'websupport',
                             search=self.search, status=self.status, 
-                            warning=self.warning, storage=self.storage)
+                            warning=self.warning, storage=self.storage,
+                            staticdir=self.staticdir)
 
         self.storage.pre_build()
         app.build()
@@ -129,7 +128,7 @@ class WebSupport(object):
 
         :param docname: the name of the document to load.
         """
-        infilename = path.join(self.outdir, docname + '.fpickle')
+        infilename = path.join(self.outdir, 'pickles', docname + '.fpickle')
 
         try:
             f = open(infilename, 'rb')

From bfbbbe5851c71706f79d823696648f96ff88af40 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 6 Aug 2010 15:07:59 -0500
Subject: [PATCH 075/127] moved _serializable_list into db.py

---
 sphinx/builders/websupport.py                 |  3 +-
 sphinx/websupport/storage/db.py               | 53 +++++++++++++++++--
 .../websupport/storage/sqlalchemystorage.py   | 48 +----------------
 3 files changed, 51 insertions(+), 53 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index eeadfc231..095bd5556 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -30,11 +30,10 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
         self.translator_class = WebSupportTranslator
 
     def write_doc(self, docname, doctree):
-        # The translator needs the docname to generate ids.
-        self.cur_docname = docname
         destination = StringOutput(encoding='utf-8')
         doctree.settings = self.docsettings
 
+        self.cur_docname = docname
         self.secnumbers = self.env.toc_secnumbers.get(docname, {})
         self.imgpath = '/' + posixpath.join(self.app.staticdir, '_images')
         self.post_process_images(doctree)
diff --git a/sphinx/websupport/storage/db.py b/sphinx/websupport/storage/db.py
index 23b6a462c..568558a3d 100644
--- a/sphinx/websupport/storage/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -16,7 +16,7 @@ from sqlalchemy import Column, Integer, Text, String, Boolean, ForeignKey,\
                        DateTime
 from sqlalchemy.schema import UniqueConstraint
 from sqlalchemy.ext.declarative import declarative_base
-from sqlalchemy.orm import relation, sessionmaker
+from sqlalchemy.orm import relation, sessionmaker, aliased
 
 Base = declarative_base()
 
@@ -33,6 +33,54 @@ class Node(Base):
     line = Column(Integer)
     source = Column(Text, nullable=False)
 
+    def nested_comments(self, username, moderator):
+        session = Session()
+
+        if username:
+            # If a username is provided, create a subquery to retrieve all
+            # votes by this user. We will outerjoin with the comment query
+            # with this subquery so we have a user's voting information.
+            sq = session.query(CommentVote).\
+                filter(CommentVote.username == username).subquery()
+            cvalias = aliased(CommentVote, sq)
+            q = session.query(Comment, cvalias.value).outerjoin(cvalias)
+        else:
+            q = session.query(Comment)
+
+        # Filter out all comments not descending from this node.
+        q = q.filter(Comment.path.like(str(self.id) + '.%'))
+        # Filter out non-displayed comments if this isn't a moderator.
+        if not moderator:
+            q = q.filter(Comment.displayed == True)
+        # Retrieve all results. Results must be ordered by Comment.path
+        # so that we can easily transform them from a flat list to a tree.
+        results = q.order_by(Comment.path).all()
+        session.close()
+
+        # We now need to convert the flat list of results to a nested
+        # lists to form the comment tree. Results will by ordered by
+        # the materialized path.
+        return self._nest_comments(results, username)
+
+    def _nest_comments(self, results, username):
+        comments = []
+        list_stack = [comments]
+        for r in results:
+            comment, vote = r if username else (r, 0)
+
+            inheritance_chain = comment.path.split('.')[1:]
+            
+            if len(inheritance_chain) == len(list_stack) + 1:
+                parent = list_stack[-1][-1]
+                list_stack.append(parent['children'])
+            elif len(inheritance_chain) < len(list_stack):
+                while len(inheritance_chain) < len(list_stack):
+                    list_stack.pop()
+
+            list_stack[-1].append(comment.serializable(vote=vote))
+        
+        return comments
+
     def __init__(self, document, line, source, treeloc):
         self.document = document
         self.line = line
@@ -52,9 +100,6 @@ class Comment(Base):
     proposal_diff = Column(Text)
     path = Column(String(256), index=True)
 
-    #node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
-    #node = relation(Node, backref='comments')
-
     def __init__(self, text, displayed, username, rating, time, 
                  proposal, proposal_diff):
         self.text = text
diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
index e96f38cf0..02fa33b50 100644
--- a/sphinx/websupport/storage/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -11,7 +11,6 @@
 
 from datetime import datetime
 
-from sqlalchemy.orm import aliased
 from sphinx.websupport.errors import *
 from sphinx.websupport.storage import StorageBackend
 from sphinx.websupport.storage.db import Base, Node, Comment, CommentVote,\
@@ -83,55 +82,10 @@ class SQLAlchemyStorage(StorageBackend):
         session = Session()
         node = session.query(Node).filter(Node.id == node_id).one()
         session.close()
-        comments = self._serializable_list(node_id, username, moderator)
+        comments = node.nested_comments(username, moderator)
         return {'source': node.source,
                 'comments': comments}
 
-    def _serializable_list(self, node_id, username, moderator):
-        session = Session()
-
-        if username:
-            # If a username is provided, create a subquery to retrieve all
-            # votes by this user. We will outerjoin with the comment query
-            # with this subquery so we have a user's voting information.
-            sq = session.query(CommentVote).\
-                filter(CommentVote.username == username).subquery()
-            cvalias = aliased(CommentVote, sq)
-            q = session.query(Comment, cvalias.value).outerjoin(cvalias)
-        else:
-            q = session.query(Comment)
-
-        # Filter out all comments not descending from this node.
-        q = q.filter(Comment.path.like(str(node_id) + '.%'))
-        # Filter out non-displayed comments if this isn't a moderator.
-        if not moderator:
-            q = q.filter(Comment.displayed == True)
-        # Retrieve all results. Results must be ordered by Comment.path
-        # so that we can easily transform them from a flat list to a tree.
-        results = q.order_by(Comment.path).all()
-        session.close()
-
-        # We now need to convert the flat list of results to a nested
-        # lists to form the comment tree. Results will by ordered by
-        # the materialized path.
-        comments = []
-        list_stack = [comments]
-        for r in results:
-            comment, vote = r if username else (r, 0)
-
-            inheritance_chain = comment.path.split('.')[1:]
-            
-            if len(inheritance_chain) == len(list_stack) + 1:
-                parent = list_stack[-1][-1]
-                list_stack.append(parent['children'])
-            elif len(inheritance_chain) < len(list_stack):
-                while len(inheritance_chain) < len(list_stack):
-                    list_stack.pop()
-
-            list_stack[-1].append(comment.serializable(vote=vote))
-        
-        return comments
-
     def process_vote(self, comment_id, username, value):
         session = Session()
         vote = session.query(CommentVote).filter(

From 307f255407ad5ff642eac510ca164928d0dbb61f Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 6 Aug 2010 16:41:10 -0500
Subject: [PATCH 076/127] add node or parent id to serializable comment

---
 sphinx/websupport/storage/db.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/sphinx/websupport/storage/db.py b/sphinx/websupport/storage/db.py
index 568558a3d..ed2b3b11c 100644
--- a/sphinx/websupport/storage/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -132,9 +132,15 @@ class Comment(Base):
                 'iso': self.time.isoformat(),
                 'delta': self.pretty_delta(delta)}
 
+        path = self.path.split('.')
+        node = path[0] if len(path) == 2 else None
+        parent = path[-2] if len(path) > 2 else None
+
         return {'text': self.text,
                 'username': self.username or 'Anonymous',
                 'id': self.id,
+                'node': node,
+                'parent': parent,
                 'rating': self.rating,
                 'age': delta.seconds,
                 'time': time,

From 63e96b2fd5d127a372a891953fbfcdb64994825c Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 6 Aug 2010 17:22:05 -0500
Subject: [PATCH 077/127] check for next in differ

---
 sphinx/websupport/storage/differ.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/websupport/storage/differ.py b/sphinx/websupport/storage/differ.py
index 4e5660c59..c82ba7427 100644
--- a/sphinx/websupport/storage/differ.py
+++ b/sphinx/websupport/storage/differ.py
@@ -39,7 +39,7 @@ class CombinedHtmlDiff(object):
         elif prefix == '?':
             return ''
         
-        if next[0] == '?':
+        if next is not None and next[0] == '?':
             tag = 'ins' if prefix == '+' else 'del'
             text = self._highlight_text(text, next, tag)
         css_class = 'prop_added' if prefix == '+' else 'prop_removed'

From 1d98a50bdc5fb6256e2c66d1384267208a15597a Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 6 Aug 2010 21:13:06 -0500
Subject: [PATCH 078/127] add moderator kwarg to moderation methods.

---
 sphinx/websupport/__init__.py   | 8 ++++++--
 sphinx/websupport/storage/db.py | 1 +
 tests/test_websupport.py        | 7 +++++--
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 29a0b0eee..4812bb932 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -286,16 +286,20 @@ class WebSupport(object):
         """
         self.storage.update_username(old_username, new_username)
 
-    def accept_comment(self, comment_id):
+    def accept_comment(self, comment_id, moderator=False):
         """Accept a comment that is pending moderation.
 
         :param comment_id: The id of the comment that was accepted.
         """
+        if not moderator:
+            raise UserNotAuthorizedError()
         self.storage.accept_comment(comment_id)
 
-    def reject_comment(self, comment_id):
+    def reject_comment(self, comment_id, moderator=False):
         """Reject a comment that is pending moderation.
 
         :param comment_id: The id of the comment that was accepted.
         """
+        if not moderator:
+            raise UserNotAuthorizedError()
         self.storage.reject_comment(comment_id)
diff --git a/sphinx/websupport/storage/db.py b/sphinx/websupport/storage/db.py
index ed2b3b11c..12c1e1d5e 100644
--- a/sphinx/websupport/storage/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -142,6 +142,7 @@ class Comment(Base):
                 'node': node,
                 'parent': parent,
                 'rating': self.rating,
+                'displayed': self.displayed,
                 'age': delta.seconds,
                 'time': time,
                 'vote': vote or 0,
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 2db29a2e1..37f0a679e 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -234,8 +234,11 @@ def test_moderation(support):
                                    displayed=False)
     # Make sure the moderation_callback is called.
     assert called == True
-    support.accept_comment(accepted['id'])
-    support.reject_comment(rejected['id'])
+    # Make sure the user must be a moderator.
+    raises(UserNotAuthorizedError, support.accept_comment, accepted['id'])
+    raises(UserNotAuthorizedError, support.reject_comment, accepted['id'])
+    support.accept_comment(accepted['id'], moderator=True)
+    support.reject_comment(rejected['id'], moderator=True)
     comments = support.get_data(3)['comments']
     assert len(comments) == 1
     comments = support.get_data(3, moderator=True)['comments']

From 690380b9f0b446866fc35efe8279c092834a5e60 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 7 Aug 2010 11:49:38 -0500
Subject: [PATCH 079/127] add DOCUMENTATION_OPTIONS to context

---
 sphinx/builders/websupport.py | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 095bd5556..70ce5d2bc 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -11,6 +11,7 @@
 
 import cPickle as pickle
 from os import path
+from cgi import escape
 import posixpath
 import shutil
 from docutils.io import StringOutput
@@ -81,7 +82,8 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
 
         # Create a dict that will be pickled and used by webapps.
         doc_ctx = {'body': ctx.get('body', ''),
-                   'title': ctx.get('title', '')}
+                   'title': ctx.get('title', ''),
+                   'DOCUMENTATION_OPTIONS': self._make_doc_options(ctx)}
         # Partially render the html template to proved a more useful ctx.
         template = self.templates.environment.get_template(templatename)
         template_module = template.make_module(ctx)
@@ -118,3 +120,17 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
 
     def dump_search_index(self):
         self.indexer.finish_indexing()
+
+    def _make_doc_options(self, ctx):
+        t = """
+var DOCUMENTATION_OPTIONS = {
+  URL_ROOT: '%s',
+  VERSION: '%s',
+  COLLAPSE_INDEX: false,
+  FILE_SUFFIX: '',
+  HAS_SOURCE: '%s'
+};""" 
+        return t % (ctx.get('url_root', ''), escape(ctx['release']),
+                    str(ctx['has_source']).lower())
+
+

From c5c5a3a69369b078cd4a3cb2fcfb73a69f0966b0 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 7 Aug 2010 14:10:49 -0500
Subject: [PATCH 080/127] add COMMENT_OPTIONS to context

---
 sphinx/websupport/__init__.py | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 4812bb932..de719e36d 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -35,12 +35,14 @@ class WebSupport(object):
     """
     def __init__(self, srcdir='', outdir='', datadir='', search=None,
                  storage=None, status=sys.stdout, warning=sys.stderr,
-                 moderation_callback=None, staticdir='static'):
+                 moderation_callback=None, staticdir='static',
+                 docroot=''):
         self.srcdir = srcdir
         self.outdir = outdir or datadir
         self.staticdir = staticdir.strip('/')
         self.status = status
         self.warning = warning
+        self.docroot = docroot.strip('/')
         self.moderation_callback = moderation_callback
 
         self._init_templating()
@@ -106,7 +108,7 @@ class WebSupport(object):
         app.build()
         self.storage.post_build()
 
-    def get_document(self, docname):
+    def get_document(self, docname, username='', moderator=False):
         """Load and return a document from a pickle. The document will
         be a dict object which can be used to render a template::
 
@@ -137,8 +139,32 @@ class WebSupport(object):
                 'The document "%s" could not be found' % docname)
 
         document = pickle.load(f)
+        document['COMMENT_OPTIONS'] = self._make_comment_options(username,
+                                                                 moderator)
         return document
 
+    def _make_comment_options(self, username, moderator):
+        parts = ['var COMMENT_OPTIONS = {']
+        if self.docroot is not '':
+            parts.append('addCommentURL: "/%s/%s",' % (self.docroot, 
+                                                       'add_comment'))
+            parts.append('getCommentsURL: "/%s/%s",' % (self.docroot, 
+                                                        'get_comments'))
+            parts.append('processVoteURL: "/%s/%s",' % (self.docroot, 
+                                                        'process_vote'))
+            parts.append('acceptCommentURL: "/%s/%s",' % (self.docroot, 
+                                                          'accept_comment'))
+            parts.append('rejectCommentURL: "/%s/%s",' % (self.docroot, 
+                                                          'reject_comment'))
+            parts.append('deleteCommentURL: "/%s/%s",' % (self.docroot, 
+                                                          'delete_comment'))
+        if username is not '':
+            parts.append('voting: true,')
+            parts.append('username: "%s",' % username)
+        parts.append('moderator: %s' % str(moderator).lower())
+        parts.append('};')
+        return '\n'.join(parts)            
+
     def get_search_results(self, q):
         """Perform a search for the query `q`, and create a set
         of search results. Then render the search results as html and

From 76fcd457b2723ec4307f92a254beabf7ab9963b1 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 7 Aug 2010 17:04:45 -0500
Subject: [PATCH 081/127] updated docs

---
 doc/web/api.rst             |   2 +-
 doc/web/quickstart.rst      | 173 +++++++++++-------------------------
 doc/web/storagebackends.rst |  12 +--
 3 files changed, 58 insertions(+), 129 deletions(-)

diff --git a/doc/web/api.rst b/doc/web/api.rst
index 0b86309c0..fcd0513ee 100644
--- a/doc/web/api.rst
+++ b/doc/web/api.rst
@@ -22,7 +22,7 @@ Methods
 
 .. automethod:: sphinx.websupport.WebSupport.get_document
 
-.. automethod:: sphinx.websupport.WebSupport.get_comments
+.. automethod:: sphinx.websupport.WebSupport.get_data
 
 .. automethod:: sphinx.websupport.WebSupport.add_comment
 
diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
index 16c650c27..b0a60507a 100644
--- a/doc/web/quickstart.rst
+++ b/doc/web/quickstart.rst
@@ -24,7 +24,15 @@ class and call it's :meth:`~sphinx.websupport.WebSupport.build` method::
 This will read reStructuredText sources from `srcdir` and place the
 necessary data in `outdir`. This directory contains all the data needed
 to display documents, search through documents, and add comments to
-documents.
+documents. It will also contain a subdirectory named "static", which
+contains static files. These files will be linked to by Sphinx documents,
+and should be served from "/static".
+
+.. note::
+
+    If you wish to serve static files from a path other than "/static", you
+    can do so by providing the *staticdir* keyword argument when creating
+    the :class:`~sphinx.websupport.api.WebSupport` object.
 
 Integrating Sphinx Documents Into Your Webapp
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -51,6 +59,8 @@ This will return a dictionary containing the following items:
 * **sidebar**: The sidebar of the document as HTML  
 * **relbar**: A div containing links to related documents
 * **title**: The title of the document
+* **DOCUMENTATION_OPTIONS**: Javascript containing documentation options
+* **COMMENT_OPTIONS**: Javascript containing comment options
 
 This dict can then be used as context for templates. The goal is to be
 easy to integrate with your existing templating system. An example using 
@@ -64,6 +74,15 @@ easy to integrate with your existing templating system. An example using
       {{ document.title }}
     {%- endblock %}
 
+    {%- block js %}
+      <script type="text/javascript">
+        {{ document.DOCUMENTATION_OPTIONS|safe }}
+	{{ document.COMMENT_OPTIONS|safe }}
+      </script>
+      {{ super() }}
+      <script type="text/javascript" src="/static/websupport.js"></script>
+    {%- endblock %}
+
     {%- block relbar %}
       {{ document.relbar|safe }}
     {%- endblock %}
@@ -76,18 +95,40 @@ easy to integrate with your existing templating system. An example using
       {{ document.sidebar|safe }}
     {%- endblock %}
 
-Most likely you'll want to create one function that can handle all of
-document requests. An example `Flask <http://flask.pocoo.org/>`_ function
-that performs this is::
+Authentication
+--------------
+
+To use certain features such as voting it must be possible to authenticate
+users. The details of the authentication are left to the your application.
+Once a user has been authenticated you can pass the user's details to certain
+:class:`~sphinx.websupport.WebSupport` methods using the *username* and
+*moderator* keyword arguments. The web support package will store the
+username with comments and votes. The only caveat is that if you allow users
+to change their username, you must update the websupport package's data::
+
+   support.update_username(old_username, new_username)
+
+*username* should be a unique string which identifies a user, and *moderator*
+should be a boolean representing whether the user has moderation
+privilieges. The default value for *moderator* is *False*.
+
+An example `Flask <http://flask.pocoo.org/>`_ function that checks whether
+a user is logged in, and the retrieves a document is::
 
     @app.route('/<path:docname>')
     def doc(docname):
-        document = support.get_document(docname)
+        if g.user:
+	    document = support.get_document(docname, g.user.name,
+	                                    g.user.moderator)
+	else:
+	    document = support.get_document(docname)
         return render_template('doc.html', document=document)
 
-This captures the request path, and passes it directly to 
-:meth:`~sphinx.websupport.WebSupport.get_document`, which then retrieves
-the correct document.
+The first thing to notice is that the *docname* is just the request path.
+If the user is authenticated then the username and moderation status are
+passed along with the docname to 
+:meth:`~sphinx.websupport.WebSupport.get_document`. The web support package
+will then add this data to the COMMENT_OPTIONS that are used in the template.
 
 .. note::
 
@@ -122,118 +163,6 @@ dict in the same format that
 Comments
 ~~~~~~~~
 
-The web support package provides a way to attach comments to some nodes
-in your document. It marks these nodes by adding a class and id to these
-nodes. A client side script can then locate these nodes, and manipulate
-them to allow commenting. A `jQuery <http://jquery.com>`_ script is also 
-being developed that will be included when it's complete. For now you can 
-find the script here: `websupport.js <http://bit.ly/cyaRaF>`_. This script 
-will use AJAX for all communications with the server. You can create your 
-own script for the front end if this doesn't meet your needs. More 
-information on that can be found :ref:`here <websupportfrontend>`.
-
-Before loading this script in your page, you need to create a COMMENT_OPTIONS
-object describing how the script should function. In the simplest case you
-will just need tell the script whether the current user is allowed to vote.
-Once this is done you can import the script as you would any other:
-
-.. sourcecode:: guess
-
-    <script type="text/javascript">
-      var COMMENT_OPTIONS =  {
-        {%- if g.user %}
-	  voting: true,
-	{%- endif %}
-      }
-    </script>
-    <script type="text/javascript" src="/static/websupport.js></script>
-
-You will then need to define some templates that the script uses to 
-display comments. The first template defines the layout for the popup 
-div used to display comments:
-
-.. sourcecode:: guess
-
-   <script type="text/html" id="popup_template">
-     <div class="popup_comment">
-       <a id="comment_close" href="#">x</a>
-       <h1>Comments</h1>
-       <form method="post" id="comment_form" action="/docs/add_comment">
- 	 <textarea name="comment"></textarea>
-	 <input type="submit" value="add comment" id="comment_button" />
-	 <input type="hidden" name="parent" />
-       <p class="sort_options">
-	 Sort by: 
-	 <a href="#" class="sort_option" id="rating">top</a>
-	 <a href="#" class="sort_option" id="ascage">newest</a>
-	 <a href="#" class="sort_option" id="age">oldest</a>
-       </p>
-       </form>
-       <h3 id="comment_notification">loading comments... <img src="/static/ajax-loader.gif" alt="" /></h3>
-       <ul id="comment_ul"></ul>
-     </div>
-     <div id="focuser"></div>
-   </script> 
-
-The next template is an `li` that contains the form used to 
-reply to a comment:
-
-.. sourcecode:: guess
-
-   <script type="text/html" id="reply_template">
-     <li>
-       <div class="reply_div" id="rd<%id%>">
-	 <form id="rf<%id%>">
-	   <textarea name="comment"></textarea>
-           <input type="submit" value="add reply" />
-           <input type="hidden" name="parent" value="c<%id%>" />
-         </form>
-       </div>
-     </li>
-   </script>
-
-The final template contains HTML that will be used to display comments
-in the comment tree:
-
-.. sourcecode:: guess
-
-   <script type="text/html" id="comment_template">
-     <div  id="cd<%id%>" class="spxcdiv">
-       <div class="vote">
-	 <div class="arrow">
-	   <a href="#" id="uv<%id%>" class="vote">
-	     <img src="<%upArrow%>" />
-	   </a>
-	   <a href="#" id="uu<%id%>" class="un vote">
-	     <img src="<%upArrowPressed%>" />
-	   </a>
-	 </div>
-	 <div class="arrow">
-	   <a href="#" id="dv<%id%>" class="vote">
-	     <img src="<%downArrow%>" id="da<%id%>" />
-	   </a>
-	   <a href="#" id="du<%id%>" class="un vote">
-	     <img src="<%downArrowPressed%>" />
-	   </a>
-	 </div>
-       </div>
-       <div class="comment_content">
-	 <p class="tagline comment">
-	   <span class="user_id"><%username%></span>
-	   <span class="rating"><%pretty_rating%></span>
-	   <span class="delta"><%time.delta%></span>
-	 </p>
-	 <p class="comment_text comment"><%text%></p>
-	 <p class="comment_opts comment">
-	   <a href="#" class="reply" id="rl<%id%>">reply</a>
-	   <a href="#" class="close_reply" id="cr<%id%>">hide</a>
-	 </p>
-	 <ul class="children" id="cl<%id%>"></ul>
-       </div>
-       <div class="clearleft"></div>
-     </div>
-   </script>
-
 Now that this is done it's time to define the functions that handle
 the AJAX calls from the script. You will need three functions. The first
 function is used to add a new comment, and will call the web support method
@@ -248,13 +177,13 @@ function is used to add a new comment, and will call the web support method
         return jsonify(comment=comment)
 
 Then next function handles the retrieval of comments for a specific node, 
-and is aptly named :meth:`~sphinx.websupport.WebSupport.get_comments`::
+and is aptly named :meth:`~sphinx.websupport.WebSupport.get_data`::
 
     @app.route('/docs/get_comments')
     def get_comments():
         user_id = g.user.id if g.user else None
         parent_id = request.args.get('parent', '')
-        comments = support.get_comments(parent_id, user_id)
+        comments = support.get_data(parent_id, user_id)
         return jsonify(comments=comments)
 
 The final function that is needed will call
diff --git a/doc/web/storagebackends.rst b/doc/web/storagebackends.rst
index 87e1b478a..4a10e1090 100644
--- a/doc/web/storagebackends.rst
+++ b/doc/web/storagebackends.rst
@@ -1,6 +1,6 @@
 .. _storagebackends:
 
-.. currentmodule:: sphinx.websupport.comments
+.. currentmodule:: sphinx.websupport.storage
 
 Storage Backends
 ================
@@ -8,12 +8,12 @@ Storage Backends
 StorageBackend Methods
 ~~~~~~~~~~~~~~~~~~~~~~
 
-.. automethod:: sphinx.websupport.comments.StorageBackend.pre_build
+.. automethod:: sphinx.websupport.storage.StorageBackend.pre_build
 
-.. automethod:: sphinx.websupport.comments.StorageBackend.add_node
+.. automethod:: sphinx.websupport.storage.StorageBackend.add_node
 
-.. automethod:: sphinx.websupport.comments.StorageBackend.post_build
+.. automethod:: sphinx.websupport.storage.StorageBackend.post_build
 
-.. automethod:: sphinx.websupport.comments.StorageBackend.add_comment
+.. automethod:: sphinx.websupport.storage.StorageBackend.add_comment
 
-.. automethod:: sphinx.websupport.comments.StorageBackend.get_comments
+.. automethod:: sphinx.websupport.storage.StorageBackend.get_data

From 4939ed27864466a86d2bd6609b85f2e3c65394e2 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 7 Aug 2010 18:44:22 -0500
Subject: [PATCH 082/127] add css and js to context

---
 sphinx/builders/websupport.py | 45 +++++++++++++++++++++++++----------
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 70ce5d2bc..bc15b8c97 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -83,7 +83,8 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
         # Create a dict that will be pickled and used by webapps.
         doc_ctx = {'body': ctx.get('body', ''),
                    'title': ctx.get('title', ''),
-                   'DOCUMENTATION_OPTIONS': self._make_doc_options(ctx)}
+                   'css': self._make_css(ctx),
+                   'js': self._make_js(ctx)}
         # Partially render the html template to proved a more useful ctx.
         template = self.templates.environment.get_template(templatename)
         template_module = template.make_module(ctx)
@@ -121,16 +122,36 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     def dump_search_index(self):
         self.indexer.finish_indexing()
 
-    def _make_doc_options(self, ctx):
-        t = """
-var DOCUMENTATION_OPTIONS = {
-  URL_ROOT: '%s',
-  VERSION: '%s',
-  COLLAPSE_INDEX: false,
-  FILE_SUFFIX: '',
-  HAS_SOURCE: '%s'
-};""" 
-        return t % (ctx.get('url_root', ''), escape(ctx['release']),
-                    str(ctx['has_source']).lower())
+    def _make_css(self, ctx):
+        def make_link(file):
+            path = ctx['pathto'](file, 1)
+            return '<link rel="stylesheet" href="%s" type=text/css />' % path
 
+        links = [make_link('_static/pygments.css')]
+        for file in ctx['css_files']:
+            links.append(make_link(file))
+        return '\n'.join(links)
+
+    def _make_js(self, ctx):
+        def make_script(file):
+            path = ctx['pathto'](file, 1)
+            return '<script type="text/javascript" src="%s"></script>' % path
+
+        opts = """
+<script type="text/javascript">
+  var DOCUMENTATION_OPTIONS = {
+    URL_ROOT: '%s',
+    VERSION: '%s',
+    COLLAPSE_INDEX: false,
+    FILE_SUFFIX: '',
+    HAS_SOURCE: '%s'
+  };
+</script>""" 
+        opts = opts % (ctx.get('url_root', ''), escape(ctx['release']),
+                       str(ctx['has_source']).lower())
+        scripts = []
+        for file in ctx['script_files']:
+            scripts.append(make_script(file))
+        scripts.append(make_script('_static/websupport.js'))
+        return opts + '\n' + '\n'.join(scripts)
 

From bf7a6526f52f175951d9da86b45c1c95e9fdf5e4 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 7 Aug 2010 18:59:11 -0500
Subject: [PATCH 083/127] moved websupport.js into sphinx

---
 sphinx/themes/basic/static/websupport.js | 751 +++++++++++++++++++++++
 1 file changed, 751 insertions(+)
 create mode 100644 sphinx/themes/basic/static/websupport.js

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
new file mode 100644
index 000000000..0e2b44303
--- /dev/null
+++ b/sphinx/themes/basic/static/websupport.js
@@ -0,0 +1,751 @@
+(function($) {
+  $.fn.autogrow = function(){
+    return this.each(function(){
+      var textarea = this;
+
+      $.fn.autogrow.resize(textarea);
+
+      $(textarea)
+	.focus(function() {
+	  textarea.interval = setInterval(function() {
+	    $.fn.autogrow.resize(textarea);
+	  }, 500);
+	})
+	.blur(function() {
+	  clearInterval(textarea.interval);
+	});
+    });
+  };
+
+  $.fn.autogrow.resize = function(textarea) {
+    var lineHeight = parseInt($(textarea).css('line-height'));
+    var lines = textarea.value.split('\n');
+    var columns = textarea.cols;
+    var lineCount = 0;
+    $.each(lines, function() {
+      lineCount += Math.ceil(this.length/columns) || 1;
+    });
+    var height = lineHeight*(lineCount+1);
+    $(textarea).css('height', height);
+  };
+})(jQuery);
+
+(function($) {
+  var commentListEmpty, popup, comp;
+
+  function init() {
+    initTemplates();
+    initEvents();
+    initComparator();
+  };
+
+  function initEvents() {
+    $('a#comment_close').click(function(event) {
+      event.preventDefault();
+      hide();
+    });
+    $('form#comment_form').submit(function(event) {
+      event.preventDefault();
+      addComment($('form#comment_form'));
+    });
+    $('.vote').live("click", function() {
+      handleVote($(this));
+      return false;
+    });
+    $('a.reply').live("click", function() {
+      openReply($(this).attr('id').substring(2));
+      return false;
+    });
+    $('a.close_reply').live("click", function() {
+      closeReply($(this).attr('id').substring(2));
+      return false;
+    });
+    $('a.sort_option').click(function(event) {
+      event.preventDefault();
+      handleReSort($(this));
+    });
+    $('a.show_proposal').live("click", function() {
+      showProposal($(this).attr('id').substring(2));
+      return false;
+    });
+    $('a.hide_proposal').live("click", function() {
+      hideProposal($(this).attr('id').substring(2));
+      return false;
+    });
+    $('a.show_propose_change').live("click", function() {
+      showProposeChange($(this).attr('id').substring(2));
+      return false;
+    });
+    $('a.hide_propose_change').live("click", function() {
+      hideProposeChange($(this).attr('id').substring(2));
+      return false;
+    });
+    $('a.accept_comment').live("click", function() {
+      acceptComment($(this).attr('id').substring(2));
+      return false;
+    });
+    $('a.reject_comment').live("click", function() {
+      rejectComment($(this).attr('id').substring(2));
+      return false;
+    });
+    $('a.delete_comment').live("click", function() {
+      deleteComment($(this).attr('id').substring(2));
+      return false;
+    });
+  };
+
+  function initTemplates() {
+    // Create our popup div, the same div is recycled each time comments
+    // are displayed.
+    popup = $(renderTemplate(popupTemplate, opts));
+    // Setup autogrow on the textareas
+    popup.find('textarea').autogrow();
+    $('body').append(popup);
+  };
+
+  /**
+   * Create a comp function. If the user has preferences stored in
+   * the sortBy cookie, use those, otherwise use the default.
+   */
+  function initComparator() {
+    var by = 'rating'; // Default to sort by rating.
+    // If the sortBy cookie is set, use that instead.
+    if (document.cookie.length > 0) {
+      var start = document.cookie.indexOf('sortBy=');
+      if (start != -1) {
+	start = start + 7;
+	var end = document.cookie.indexOf(";", start);
+	if (end == -1)
+	  end = document.cookie.length;
+	by = unescape(document.cookie.substring(start, end));
+      }
+    }
+    setComparator(by);
+  };
+
+  /**
+   * Show the comments popup window.
+   */
+  function show(nodeId) {
+    var id = nodeId.substring(1);
+
+    // Reset the main comment form, and set the value of the parent input.
+    $('form#comment_form')
+      .find('textarea,input')
+	.removeAttr('disabled').end()
+      .find('input[name="node"]')
+	.val(id).end()
+      .find('textarea[name="proposal"]')
+	.val('')
+	.hide();
+
+    // Position the popup and show it.
+    var clientWidth = document.documentElement.clientWidth;
+    var popupWidth = $('div.popup_comment').width();
+    $('div#focuser').fadeIn('fast');
+    $('div.popup_comment')
+      .css({
+	'top': 100+$(window).scrollTop(),
+	'left': clientWidth/2-popupWidth/2,
+	'position': 'absolute'
+      })
+      .fadeIn('fast', function() {
+	getComments(id);
+      });
+  };
+
+  /**
+   * Hide the comments popup window.
+   */
+  function hide() {
+    $('div#focuser').fadeOut('fast');
+    $('div.popup_comment').fadeOut('fast', function() {
+      $('ul#comment_ul').empty();
+      $('h3#comment_notification').show();
+      $('form#comment_form').find('textarea')
+	.val('').end()
+	.find('textarea, input')
+	  .removeAttr('disabled');
+    });
+  };
+
+  /**
+   * Perform an ajax request to get comments for a node
+   * and insert the comments into the comments tree.
+   */
+  function getComments(id) {
+    $.ajax({
+      type: 'GET',
+      url: opts.getCommentsURL,
+      data: {node: id},
+      success: function(data, textStatus, request) {
+	var ul = $('ul#comment_ul').hide();
+	$('form#comment_form')
+	  .find('textarea[name="proposal"]')
+	    .data('source', data.source);
+
+	if (data.comments.length == 0) {
+	  ul.html('<li>No comments yet.</li>');
+	  commentListEmpty = true;
+	  var speed = 100;
+	}
+	else {
+	  // If there are comments, sort them and put them in the list.
+	  var comments = sortComments(data.comments);
+	  var speed = data.comments.length * 100;
+	  appendComments(comments, ul);
+	  commentListEmpty = false;
+	}
+	$('h3#comment_notification').slideUp(speed+200);
+	ul.slideDown(speed);
+      },
+      error: function(request, textStatus, error) {
+	showError('Oops, there was a problem retrieving the comments.');
+      },
+      dataType: 'json'
+    });
+  };
+
+  /**
+   * Add a comment via ajax and insert the comment into the comment tree.
+   */
+  function addComment(form) {
+    // Disable the form that is being submitted.
+    form.find('textarea,input').attr('disabled', 'disabled');
+
+    // Send the comment to the server.
+    $.ajax({
+      type: "POST",
+      url: opts.addCommentURL,
+      dataType: 'json',
+      data: {node: form.find('input[name="node"]').val(),
+             parent: form.find('input[name="parent"]').val(),
+	     text: form.find('textarea[name="comment"]').val(),
+	     proposal: form.find('textarea[name="proposal"]').val()},
+      success: function(data, textStatus, error) {
+	// Reset the form.
+	form.find('textarea')
+	  .val('')
+	    .add(form.find('input'))
+	      .removeAttr('disabled');
+	if (commentListEmpty) {
+	  $('ul#comment_ul').empty();
+	  commentListEmpty = false;
+	}
+	insertComment(data.comment);
+      },
+      error: function(request, textStatus, error) {
+	form.find('textarea,input').removeAttr('disabled');
+	showError('Oops, there was a problem adding the comment.');
+      }
+    });
+  };
+
+  /**
+   * Recursively append comments to the main comment list and children
+   * lists, creating the comment tree.
+   */
+  function appendComments(comments, ul) {
+    $.each(comments, function() {
+      var div = createCommentDiv(this);
+      ul.append($('<li></li>').html(div));
+      appendComments(this.children, div.find('ul.children'));
+      // To avoid stagnating data, don't store the comments children in data.
+      this.children = null;
+      div.data('comment', this);
+    });
+  };
+
+  /**
+   * After adding a new comment, it must be inserted in the correct
+   * location in the comment tree.
+   */
+  function insertComment(comment) {
+    var div = createCommentDiv(comment);
+
+    // To avoid stagnating data, don't store the comments children in data.
+    comment.children = null;
+    div.data('comment', comment);
+
+    if (comment.node != null) {
+      var ul = $('ul#comment_ul');
+      var siblings = getChildren(ul);
+    }
+    else {
+      var ul = $('#cl' + comment.parent);
+      var siblings = getChildren(ul);
+    }
+
+    var li = $('<li></li>');
+    li.hide();
+
+    // Determine where in the parents children list to insert this comment.
+    for(i=0; i < siblings.length; i++) {
+      if (comp(comment, siblings[i]) <= 0) {
+	$('#cd' + siblings[i].id)
+	  .parent()
+	    .before(li.html(div));
+	li.slideDown('fast');
+	return;
+      }
+    }
+
+    // If we get here, this comment rates lower than all the others,
+    // or it is the only comment in the list.
+    ul.append(li.html(div));
+    li.slideDown('fast');
+  };
+
+  function acceptComment(id) {
+    $.ajax({
+      type: 'POST',
+      url: opts.acceptCommentURL,
+      data: {id: id},
+      success: function(data, textStatus, request) {
+	$('#cm' + id).fadeOut('fast');
+      },
+      error: function(request, textStatus, error) {
+	showError("Oops, there was a problem accepting the comment.");
+      },
+    });
+  };
+
+  function rejectComment(id) {
+    $.ajax({
+      type: 'POST',
+      url: opts.rejectCommentURL,
+      data: {id: id},
+      success: function(data, textStatus, request) {
+	var div = $('#cd' + id);
+	div.slideUp('fast', function() {
+	  div.remove();
+	});
+      },
+      error: function(request, textStatus, error) {
+	showError("Oops, there was a problem rejecting the comment.");
+      },
+    });
+  };
+
+  function deleteComment(id) {
+    $.ajax({
+      type: 'POST',
+      url: opts.deleteCommentURL,
+      data: {id: id},
+      success: function(data, textStatus, request) {
+	var div = $('#cd' + id);
+	div
+	  .find('span.user_id:first')
+	    .text('[deleted]').end()
+	  .find('p.comment_text:first')
+	    .text('[deleted]').end()
+	  .find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id +
+		', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id)
+	    .remove();
+	var comment = div.data('comment');
+	comment.username = '[deleted]';
+	comment.text = '[deleted]';
+	div.data('comment', comment);
+      },
+      error: function(request, textStatus, error) {
+	showError("Oops, there was a problem deleting the comment.");
+      },
+    });
+  };
+
+  function showProposal(id) {
+    $('#sp' + id).hide();
+    $('#hp' + id).show();
+    $('#pr' + id).slideDown('fast');
+  };
+
+  function hideProposal(id) {
+    $('#hp' + id).hide();
+    $('#sp' + id).show();
+    $('#pr' + id).slideUp('fast');
+  };
+
+  function showProposeChange(id) {
+    $('a.show_propose_change').hide();
+    $('a.hide_propose_change').show();
+    var textarea = $('textarea[name="proposal"]');
+    textarea.val(textarea.data('source'));
+    $.fn.autogrow.resize(textarea[0]);
+    textarea.slideDown('fast');
+  };
+
+  function hideProposeChange(id) {
+    $('a.hide_propose_change').hide();
+    $('a.show_propose_change').show();
+    var textarea = $('textarea[name="proposal"]');
+    textarea.val('');
+    textarea.slideUp('fast');
+  };
+
+  /**
+   * Handle when the user clicks on a sort by link.
+   */
+  function handleReSort(link) {
+    setComparator(link.attr('id'));
+     // Save/update the sortBy cookie.
+    var expiration = new Date();
+    expiration.setDate(expiration.getDate() + 365);
+    document.cookie= 'sortBy=' + escape(link.attr('id')) +
+      ';expires=' + expiration.toUTCString();
+    var comments = getChildren($('ul#comment_ul'), true);
+    comments = sortComments(comments);
+
+    appendComments(comments, $('ul#comment_ul').empty());
+  };
+
+  /**
+   * Function to process a vote when a user clicks an arrow.
+   */
+  function handleVote(link) {
+    if (!opts.voting) {
+      showError("You'll need to login to vote.");
+      return;
+    }
+
+    var id = link.attr('id');
+    // If it is an unvote, the new vote value is 0,
+    // Otherwise it's 1 for an upvote, or -1 for a downvote.
+    if (id.charAt(1) == 'u')
+      var value = 0;
+    else
+      var value = id.charAt(0) == 'u' ? 1 : -1;
+
+    // The data to be sent to the server.
+    var d = {
+      comment_id: id.substring(2),
+      value: value
+    };
+
+    // Swap the vote and unvote links.
+    link.hide();
+    $('#' + id.charAt(0) + (id.charAt(1) == 'u' ? 'v' : 'u') + d.comment_id)
+      .show();
+
+    // The div the comment is displayed in.
+    var div = $('div#cd' + d.comment_id);
+    var data = div.data('comment');
+
+    // If this is not an unvote, and the other vote arrow has
+    // already been pressed, unpress it.
+    if ((d.value != 0) && (data.vote == d.value*-1)) {
+      $('#' + (d.value == 1 ? 'd' : 'u') + 'u' + d.comment_id)
+	.hide();
+      $('#' + (d.value == 1 ? 'd' : 'u') + 'v' + d.comment_id)
+	.show();
+    }
+
+    // Update the comments rating in the local data.
+    data.rating += (data.vote == 0) ? d.value : (d.value - data.vote);
+    data.vote = d.value;
+    div.data('comment', data);
+
+    // Change the rating text.
+    div.find('.rating:first')
+      .text(data.rating + ' point' + (data.rating == 1 ? '' : 's'));
+
+    // Send the vote information to the server.
+    $.ajax({
+      type: "POST",
+      url: opts.processVoteURL,
+      data: d,
+      error: function(request, textStatus, error) {
+	showError("Oops, there was a problem casting that vote.");
+      }
+    });
+  };
+
+  /**
+   * Open a reply form used to reply to an existing comment.
+   */
+  function openReply(id) {
+    // Swap out the reply link for the hide link
+    $('#rl' + id).hide();
+    $('#cr' + id).show();
+
+    // Add the reply li to the children ul.
+    var div = $(renderTemplate(replyTemplate, {id: id})).hide();
+    $('#cl' + id)
+      .prepend(div)
+      // Setup the submit handler for the reply form.
+      .find('#rf' + id)
+	.submit(function(event) {
+	  event.preventDefault();
+	  addComment($('#rf' + id));
+	  closeReply(id);
+	});
+    div.slideDown('fast');
+  };
+
+  /**
+   * Close the reply form opened with openReply.
+   */
+  function closeReply(id) {
+    // Remove the reply div from the DOM.
+    $('#rd' + id).slideUp('fast', function() {
+      $(this).remove();
+    });
+
+    // Swap out the hide link for the reply link
+    $('#cr' + id).hide();
+    $('#rl' + id).show();
+  };
+
+  /**
+   * Recursively sort a tree of comments using the comp comparator.
+   */
+  function sortComments(comments) {
+    comments.sort(comp);
+    $.each(comments, function() {
+      this.children = sortComments(this.children);
+    });
+    return comments;
+  };
+
+  /**
+   * Set comp, which is a comparator function used for sorting and
+   * inserting comments into the list.
+   */
+  function setComparator(by) {
+    // If the first three letters are "asc", sort in ascending order
+    // and remove the prefix.
+    if (by.substring(0,3) == 'asc') {
+      var i = by.substring(3);
+      comp = function(a, b) { return a[i] - b[i]; }
+    }
+    // Otherwise sort in descending order.
+    else
+      comp = function(a, b) { return b[by] - a[by]; }
+
+    // Reset link styles and format the selected sort option.
+    $('a.sel').attr('href', '#').removeClass('sel');
+    $('#' + by).removeAttr('href').addClass('sel');
+  };
+
+  /**
+   * Get the children comments from a ul. If recursive is true,
+   * recursively include childrens' children.
+   */
+  function getChildren(ul, recursive) {
+    var children = [];
+    ul.children().children("[id^='cd']")
+      .each(function() {
+	var comment = $(this).data('comment');
+	if (recursive) {
+	  comment.children =
+	    getChildren($(this).find('#cl' + comment.id), true);
+	}
+	children.push(comment);
+      });
+    return children;
+  };
+
+  /**
+   * Create a div to display a comment in.
+   */
+  function createCommentDiv(comment) {
+    // Prettify the comment rating.
+    comment.pretty_rating = comment.rating + ' point' +
+      (comment.rating == 1 ? '' : 's');
+    // Create a div for this comment.
+    var context = $.extend({}, opts, comment);
+    var div = $(renderTemplate(commentTemplate, context));
+
+    // If the user has voted on this comment, highlight the correct arrow.
+    if (comment.vote) {
+      var direction = (comment.vote == 1) ? 'u' : 'd';
+      div.find('#' + direction + 'v' + comment.id).hide();
+      div.find('#' + direction + 'u' + comment.id).show();
+    }
+
+    if (comment.text != '[deleted]') {
+      div.find('a.reply').show();
+      if (comment.proposal_diff) {
+	div.find('#sp' + comment.id).show();
+      }
+      if (opts.moderator && !comment.displayed) {
+	div.find('#cm' + comment.id).show();
+      }
+      if (opts.moderator || (opts.username == comment.username)) {
+	div.find('#dc' + comment.id).show();
+      }
+    }
+
+    return div;
+  }
+
+  /**
+   * A simple template renderer. Placeholders such as <%id%> are replaced
+   * by context['id']. Items are always escaped.
+   */
+  function renderTemplate(template, context) {
+    var esc = $('<span></span>');
+
+    function handle(ph, escape) {
+      var cur = context;
+      $.each(ph.split('.'), function() {
+	cur = cur[this];
+      });
+      return escape ? esc.text(cur || "").html() : cur;
+    }
+
+    return template.replace(/<([%#])([\w\.]*)\1>/g, function(){
+      return handle(arguments[2], arguments[1] == '%' ? true : false);
+    });
+  };
+
+  function showError(message) {
+    $('<div class="popup_error">' +
+      '<h1>' + message + '</h1>' +
+      '</div>')
+	.appendTo('body')
+	  .fadeIn("slow")
+	    .delay(2000)
+	      .fadeOut("slow");
+  };
+
+  /**
+   * Add a link the user uses to open the comments popup.
+   */
+  $.fn.comment = function() {
+    return this.each(function() {
+      $(this).append(
+	$('<a href="#" class="sphinx_comment"></a>')
+	  .html(opts.commentHTML)
+	  .click(function(event) {
+	    event.preventDefault();
+	    show($(this).parent().attr('id'));
+	  }));
+    });
+  };
+
+  var replyTemplate = '    <li>\
+      <div class="reply_div" id="rd<%id%>">\
+	<form id="rf<%id%>">\
+	  <textarea name="comment"></textarea>\
+          <input type="submit" value="add reply" />\
+          <input type="hidden" name="parent" value="<%id%>" />\
+          <input type="hidden" name="node" value="" />\
+        </form>\
+      </div>\
+    </li>';
+
+  var commentTemplate = '    <div  id="cd<%id%>" class="spxcdiv">\
+      <div class="vote">\
+	<div class="arrow">\
+	  <a href="#" id="uv<%id%>" class="vote">\
+	    <img src="<%upArrow%>" />\
+	  </a>\
+	  <a href="#" id="uu<%id%>" class="un vote">\
+	    <img src="<%upArrowPressed%>" />\
+	  </a>\
+	</div>\
+      <div class="arrow">\
+	  <a href="#" id="dv<%id%>" class="vote">\
+	    <img src="<%downArrow%>" id="da<%id%>" />\
+	  </a>\
+	  <a href="#" id="du<%id%>" class="un vote">\
+	    <img src="<%downArrowPressed%>" />\
+	  </a>\
+	</div>\
+      </div>\
+      <div class="comment_content">\
+	<p class="tagline comment">\
+	  <span class="user_id"><%username%></span>\
+	  <span class="rating"><%pretty_rating%></span>\
+	  <span class="delta"><%time.delta%></span>\
+	</p>\
+	<p class="comment_text comment"><%text%></p>\
+	<p class="comment_opts comment">\
+	  <a href="#" class="reply hidden" id="rl<%id%>">reply &#9657;</a>\
+	  <a href="#" class="close_reply" id="cr<%id%>">reply &#9663;</a>\
+	  <a href="#" id="sp<%id%>" class="show_proposal">\
+	    proposal &#9657;\
+	  </a>\
+	  <a href="#" id="hp<%id%>" class="hide_proposal">\
+	    proposal &#9663;\
+	  </a>\
+	  <a href="#" id="dc<%id%>" class="delete_comment hidden">\
+	    delete\
+	  </a>\
+	  <span id="cm<%id%>" class="moderation hidden">\
+	    <a href="#" id="ac<%id%>" class="accept_comment">accept</a>\
+	    <a href="#" id="rc<%id%>" class="reject_comment">reject</a>\
+	  </span>\
+	</p>\
+	<pre class="proposal" id="pr<%id%>">\
+<#proposal_diff#>\
+	</pre>\
+	<ul class="children" id="cl<%id%>"></ul>\
+      </div>\
+      <div class="clearleft"></div>\
+    </div>';
+
+   var popupTemplate = '    <div class="popup_comment">\
+      <a id="comment_close" href="#">x</a>\
+      <h1>Comments</h1>\
+      <form method="post" id="comment_form" action="/docs/add_comment">\
+	<textarea name="comment" cols="80"></textarea>\
+	<p class="propose_button">\
+	  <a href="#" class="show_propose_change">\
+	    Propose a change &#9657;\
+	  </a>\
+	  <a href="#" class="hide_propose_change">\
+	    Propose a change &#9663;\
+	  </a>\
+	</p>\
+	<textarea name="proposal" cols="80" spellcheck="false"></textarea>\
+	<input type="submit" value="add comment" id="comment_button" />\
+	<input type="hidden" name="node" />\
+	<input type="hidden" name="parent" value="" />\
+      <p class="sort_options">\
+	Sort by:\
+	<a href="#" class="sort_option" id="rating">top</a>\
+	<a href="#" class="sort_option" id="ascage">newest</a>\
+	<a href="#" class="sort_option" id="age">oldest</a>\
+      </p>\
+      </form>\
+      <h3 id="comment_notification">loading comments... <img src="/static/ajax-loader.gif" alt="" /></h3>\
+      <ul id="comment_ul"></ul>\
+    </div>\
+    <div id="focuser"></div>';
+
+
+  var opts = jQuery.extend({
+    processVoteURL: '/process_vote',
+    addCommentURL: '/add_comment',
+    getCommentsURL: '/get_comments',
+    acceptCommentURL: '/accept_comment',
+    rejectCommentURL: '/reject_comment',
+    rejectCommentURL: '/delete_comment',
+    commentHTML: '<img src="/static/comment.png" alt="comment" />',
+    upArrow: '/static/up.png',
+    downArrow: '/static/down.png',
+    upArrowPressed: '/static/up-pressed.png',
+    downArrowPressed: '/static/down-pressed.png',
+    voting: false,
+    moderator: false
+  }, COMMENT_OPTIONS);
+
+  $(document).ready(function() {
+    init();
+  });
+})(jQuery);
+
+$(document).ready(function() {
+  $('.spxcmt').comment();
+
+  /** Highlight search words in search results. */
+  $("div.context").each(function() {
+    var params = $.getQueryParameters();
+    var terms = (params.q) ? params.q[0].split(/\s+/) : [];
+    var result = $(this);
+    $.each(terms, function() {
+      result.highlightText(this.toLowerCase(), 'highlighted');
+    });
+  });
+});
\ No newline at end of file

From 40c7de1aff9a4efe1827b915ff447e0dd5e59080 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 7 Aug 2010 19:06:28 -0500
Subject: [PATCH 084/127] update get_document to add comment options to js

---
 sphinx/websupport/__init__.py | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index de719e36d..343928135 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -139,12 +139,13 @@ class WebSupport(object):
                 'The document "%s" could not be found' % docname)
 
         document = pickle.load(f)
-        document['COMMENT_OPTIONS'] = self._make_comment_options(username,
-                                                                 moderator)
+        comment_opts = self._make_comment_options(username, moderator)
+        document['js'] = comment_opts + '\n' + document['js']
         return document
 
     def _make_comment_options(self, username, moderator):
-        parts = ['var COMMENT_OPTIONS = {']
+        parts = ['<script type="text/javascript">', 
+                 'var COMMENT_OPTIONS = {']
         if self.docroot is not '':
             parts.append('addCommentURL: "/%s/%s",' % (self.docroot, 
                                                        'add_comment'))
@@ -163,6 +164,7 @@ class WebSupport(object):
             parts.append('username: "%s",' % username)
         parts.append('moderator: %s' % str(moderator).lower())
         parts.append('};')
+        parts.append('</script>')
         return '\n'.join(parts)            
 
     def get_search_results(self, q):

From 6f3932660aed0db590e1a8a3f31293358e3aeb19 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 7 Aug 2010 20:21:53 -0500
Subject: [PATCH 085/127] an even nicer build directory

---
 sphinx/builders/websupport.py |  8 +++++---
 sphinx/websupport/__init__.py | 17 ++++++++++-------
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index bc15b8c97..cdd0fb925 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -107,7 +107,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
         # if there is a source file, copy the source file for the
         # "show source" link
         if ctx.get('sourcename'):
-            source_name = path.join(self.outdir, self.app.staticdir,
+            source_name = path.join(self.app.builddir, self.app.staticdir,
                                     '_sources',  os_path(ctx['sourcename']))
             ensuredir(path.dirname(source_name))
             copyfile(self.env.doc2path(pagename), source_name)
@@ -115,9 +115,11 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     def handle_finish(self):
         StandaloneHTMLBuilder.handle_finish(self)
         shutil.move(path.join(self.outdir, '_images'),
-                    path.join(self.outdir, self.app.staticdir, '_images'))
+                    path.join(self.app.builddir, self.app.staticdir,
+                              '_images'))
         shutil.move(path.join(self.outdir, '_static'),
-                    path.join(self.outdir, self.app.staticdir, '_static'))
+                    path.join(self.app.builddir, self.app.staticdir,
+                              '_static'))
 
     def dump_search_index(self):
         self.indexer.finish_indexing()
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 343928135..9bd6cbda5 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -25,6 +25,7 @@ from sphinx.websupport.errors import *
 class WebSupportApp(Sphinx):
     def __init__(self, *args, **kwargs):
         self.staticdir = kwargs.pop('staticdir', None)
+        self.builddir = kwargs.pop('builddir', None)
         self.search = kwargs.pop('search', None)
         self.storage = kwargs.pop('storage', None)
         Sphinx.__init__(self, *args, **kwargs)
@@ -33,16 +34,18 @@ class WebSupport(object):
     """The main API class for the web support package. All interactions
     with the web support package should occur through this class.
     """
-    def __init__(self, srcdir='', outdir='', datadir='', search=None,
+    def __init__(self, srcdir='', builddir='', datadir='', search=None,
                  storage=None, status=sys.stdout, warning=sys.stderr,
                  moderation_callback=None, staticdir='static',
                  docroot=''):
         self.srcdir = srcdir
-        self.outdir = outdir or datadir
+        self.builddir = builddir
+        self.outdir = path.join(builddir, 'data')
+        self.datadir = datadir or self.outdir
         self.staticdir = staticdir.strip('/')
+        self.docroot = docroot.strip('/')
         self.status = status
         self.warning = warning
-        self.docroot = docroot.strip('/')
         self.moderation_callback = moderation_callback
 
         self._init_templating()
@@ -58,7 +61,7 @@ class WebSupport(object):
             from sphinx.websupport.storage.sqlalchemystorage \
                 import SQLAlchemyStorage
             from sqlalchemy import create_engine
-            db_path = path.join(self.outdir, 'db', 'websupport.db')
+            db_path = path.join(self.datadir, 'db', 'websupport.db')
             ensuredir(path.dirname(db_path))
             uri = storage or 'sqlite:///%s' % db_path
             engine = create_engine(uri)
@@ -78,7 +81,7 @@ class WebSupport(object):
             mod, cls = search_adapters[search or 'null']
             mod = 'sphinx.websupport.search.' + mod
             SearchClass = getattr(__import__(mod, None, None, [cls]), cls)
-            search_path = path.join(self.outdir, 'search')
+            search_path = path.join(self.datadir, 'search')
             self.search = SearchClass(search_path)
         self.results_template = \
             self.template_env.get_template('searchresults.html')
@@ -102,7 +105,7 @@ class WebSupport(object):
                             self.outdir, doctreedir, 'websupport',
                             search=self.search, status=self.status, 
                             warning=self.warning, storage=self.storage,
-                            staticdir=self.staticdir)
+                            staticdir=self.staticdir, builddir=self.builddir)
 
         self.storage.pre_build()
         app.build()
@@ -130,7 +133,7 @@ class WebSupport(object):
 
         :param docname: the name of the document to load.
         """
-        infilename = path.join(self.outdir, 'pickles', docname + '.fpickle')
+        infilename = path.join(self.datadir, 'pickles', docname + '.fpickle')
 
         try:
             f = open(infilename, 'rb')

From 2dcb0f017827443c673c902a266c6ec0f62c52be Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sat, 7 Aug 2010 21:08:43 -0500
Subject: [PATCH 086/127] updated tests to use builddir instead of outdir

---
 tests/test_searchadapters.py | 2 +-
 tests/test_websupport.py     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/test_searchadapters.py b/tests/test_searchadapters.py
index c9525f758..cb6c6e968 100644
--- a/tests/test_searchadapters.py
+++ b/tests/test_searchadapters.py
@@ -28,7 +28,7 @@ def teardown_module():
 def search_adapter_helper(adapter):
     clear_builddir()
     
-    settings = {'outdir': os.path.join(test_root, 'websupport'),
+    settings = {'builddir': os.path.join(test_root, 'websupport'),
                 'status': StringIO(),
                 'warning': StringIO()}
     settings.update({'srcdir': test_root,
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 37f0a679e..27a14e369 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -27,7 +27,7 @@ except ImportError:
     wraps = lambda f: (lambda w: w)
 
 
-default_settings = {'outdir': os.path.join(test_root, 'websupport'),
+default_settings = {'builddir': os.path.join(test_root, 'websupport'),
                     'status': StringIO(),
                     'warning': StringIO()}
 

From 77b4c107cffcd54e4b9cc9ffd77cacf9861a917d Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sun, 8 Aug 2010 11:10:56 -0500
Subject: [PATCH 087/127] added static images used for web support

---
 sphinx/themes/basic/static/ajax-loader.gif  | Bin 0 -> 673 bytes
 sphinx/themes/basic/static/comment.png      | Bin 0 -> 3501 bytes
 sphinx/themes/basic/static/down-pressed.png | Bin 0 -> 368 bytes
 sphinx/themes/basic/static/down.png         | Bin 0 -> 363 bytes
 sphinx/themes/basic/static/up-pressed.png   | Bin 0 -> 372 bytes
 sphinx/themes/basic/static/up.png           | Bin 0 -> 363 bytes
 6 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 sphinx/themes/basic/static/ajax-loader.gif
 create mode 100644 sphinx/themes/basic/static/comment.png
 create mode 100644 sphinx/themes/basic/static/down-pressed.png
 create mode 100644 sphinx/themes/basic/static/down.png
 create mode 100644 sphinx/themes/basic/static/up-pressed.png
 create mode 100644 sphinx/themes/basic/static/up.png

diff --git a/sphinx/themes/basic/static/ajax-loader.gif b/sphinx/themes/basic/static/ajax-loader.gif
new file mode 100644
index 0000000000000000000000000000000000000000..61faf8cab23993bd3e1560bff0668bd628642330
GIT binary patch
literal 673
zcmZ?wbhEHb6krfw_{6~Q|Nno%(3)e{?)x>&1u}A`t?OF7Z|1gRivOgXi&7IyQd1Pl
zGfOfQ60;I3a`F>X^fL3(@);C=vM_KlFfb_o=k{|A33hf2a5d61U}gjg=>Rd%XaNQW
zW@C<Bcm5fi^2`=a=CI<BoWt%nBaPE_qv4@lA~O$e(@QvVsPKYrw1nl|W$cy`JnUZC
z&pm)ff{kWGHpc{Hj$e<Wf^-Yd?hVhnTne26LlO)n6%u@0qor2V$ZRdW|29#Ay+Pr+
z#G^K6$xW&%T0&5Rn2-%J<Je`StbNMy#Dp_b!t~i%lV$k6Ncw&BbV{7Dx<KXw*O|?G
zWsa@TW{P|({)e&oFu&2t6sh_9S)fKSBO3+uTav2wDWkTDZ{~!>w{|b%Y*pl8F?4B9
zlo4Fz*0kZGJabY|>}Okf0}CCg{u4`zEPY^pV?j2@h+|igy0+Kz6p;@SpM4s6)XEMg
z#3Y4GX>Hjlml5ftdH$4x0JGdn8~MX(U~_^d!Hi)=HU{V%g+mi8#UGbE-*ao8f#h+S
z2a0-5+vc7MU$e-NhmBjLIC1v|)9+Im8x1yacJ7{^tLX(ZhYi^rpmXm0`@ku9b53aN
zEXH@Y3JaztblgpxbJt{AtE1ad1Ca>{v$rwwvK(>{m~Gf_=-Ro7Fk{#;i~+{{>QtvI
yb2P8Zac~?~=sRA>$6{!(^3;ZP0TPFR(G_-UDU(8Jl0?(IXu$~#4A!880|o%~Al1tN

literal 0
HcmV?d00001

diff --git a/sphinx/themes/basic/static/comment.png b/sphinx/themes/basic/static/comment.png
new file mode 100644
index 0000000000000000000000000000000000000000..bad742bb08696f9103edeb65b301e514d1bb81de
GIT binary patch
literal 3501
zcmV;e4N~%nP)<h;3K|Lk000e1NJLTq000mG000mO1^@s6AM^iV000V4X+uL$P-t&-
zZ*ypGa3D!TLm+T+Z)Rz1WdHzp+MQEpR8#2|J@?-9LQ9B%luK_?6$l_wLW_VDktQl3
z2@pz%A)(n7QNa;KMFbnjpojyGj)066Q7jCK3fKqaA)=0hqlk*i`{8?|Yu3E?=FR@K
z*FNX0^PRKL2fzpnmPj*EHGmAMLLL#|gU7_i;p8qrfeIvW01ybXWFd3?BLM*Temp!Y
zBESc}00DT@3kU$fO`E_l9Ebl8>Oz@Z0f2-7z;ux~O9+4z06=<<LZ$#fMgf4Gm?l#I
zpacM5%VT2W08lLeU?+d((*S^-_?deF09%wH6#<};03Z`(h(rKrI{>WDR*FRcSTFz-
zW=q650N5=6FiBTtNC2?60Km==3$g$R3;-}uh=nNt1bYBr$Ri_o0EC$U6h`t_Jn<{8
z5a%iY0C<_QJh>z}MS)ugEpZ1|S1ukX&Pf+56gFW3VVXcL!g-k)GJ!M?;PcD?0HBc-
z5#WRK{dmp}uFlRjj<yb8E$Y7p{~}^y<NoE(t8hR70O53g(f%wivl@Uq27qn;q9yJG
zXkH7Tb@z*AvJXJD0HEpGSMzZAemp!yp^&-R+2!Qq*h<7gTVcvqeg0>{U%*%WZ25jX
z{P*?XzTzZ-GF^d31o+^>%=Ap99M6&ogks$0k4OBs3;+Bb(;~!4V!2o<6ys46agIcq
zjPo+3B8fthDa9qy|77CdEc*jK-!%ZRYCZvbku9iQV*~a}ClFY4z~c7+0P?$U!PF=S
z1Au6Q;m>#f??3%Vpd|o+W=WE9003S@Bra6Svp>fO002awfhw>;8}z{#EWidF!3EsG
z3;bX<ghC|5!a@*23S@vBa$qT}f<h>U&9EIRU@z1_9W=mEXoiz;4lcq~xDGvV5BgyU
zp1~-*fe8db$Osc*A=-!mVv1NJjtCc-h4>-CNCXm#Bp}I%6j35eku^v$Qi@a{RY)E3
zJ#qp$hg?Rwkvqr$GJ^buyhkyVfwECO)C{#lxu`c9ghrwZ&}4KmnvWKso6vH!8a<3Q
zq36)6Xb;+tK10Vaz~~qUGsJ8#F2=(`u{bOVlVi)VBCHIn#u~6ztOL7=^<&SmcLWlF
zMZgI*1b0FpVIDz9SWH+>*hr`#93(Um+6gxa1B6k+CnA%mOSC4s5&6UzVlpv@SV$}*
z))J2sFA#f(L&P^E5{W}HC%KRUNwK6<(h|}}(r!{C=`5+6G)NjFlgZj-YqAG9lq?`C
z$c5yc<iq4M<QwE6@>>d>VnA`E_*3F2Qp##d8RZb=H01_mm@+|Cqnc9PsG(F5HIG_C
zt)aG3uTh7n6Et<2In9F>NlT@zqLtGcXcuVrX|L#Xx)I%#9!{6gSJKPrN9dR61N3(c
z4Tcqi$B1Vr8Jidf7-t!G7_XR2rWw<V8OKyGH!<s&=a~<gZ&g?-wkmuTk;)2{N|h#+
z8!9hUsj8-`-l_{#^Hs}KkEvc$eXd4TGgITK3DlOWRjQp(>r)$3XQ?}=hpK0&Z&W{|
zep&sA23f;Q!%st`QJ}G3<GjWo3u76xcq}1n4XcKAfi=V?vCY|hb}GA={T;iDJ*ugp
zIYTo_Ggq@x^OR;k2jiG=_?&c33Fj!Mm-Bv#-W2aC;wc-ZG)%cMWn62jmY0@Tt4OO+
zt4Hg-Hm>cbou<7-yIK2z4nfCCCtN2-XOGSWo##{8Q{ATurxr~;I`ytDs%xbip}RzP
zziy}Qn4Z2~fSycmr`~zJ=lUFdFa1>gZThG6M+{g7vkW8#+YHVaJjFF}Z#*3@$J_By
zLtVo_L#1JrVVB{Ak-5=4qt!-@Mh}c>#$4kh<88)m#-k<%CLtzEP3leVno>=<rYWX7
zOgl`+&CJcB&DNPUn>{htGUuD;o7bD)w_sX$S}eAxwzy?UvgBH(S?;#HZiQMoS*2K2
zT3xe7t(~nU*1N5{rxB;QPLocnp4Ml>u<^FZwyC!nu;thW+pe~4wtZn|Vi#w(#jeBd
zlf9FDx_yoPJqHbk*$%56S{;6Kv~m<WRyy9A&YbQ)eZ};a=`Uwk&k)bpGvl@s%PGWZ
zol~3BM`ssjxpRZ_h>M9!g3B(KJ}#RZ#@)!h<Vtk)ab4kh()FF2vzx;0sN1jZHtuQe
zhuojcG@mJ+Su=Cc!^lJ6QRUG;3!jxRYu~JXPeV_EXSL@eFJmu}SFP8ux21Qg_hIiB
zKK4FxpW{B`JU8Al-dSJFH^8^Zx64n%Z=PR;-$Q>R|78Dq|Iq-afF%KE1Brn_fm;Im
z_<DRHzm7jT+hz8$+3i7$pt(U6L63s1g5|-jA!x|#kgXy2=a|ls&S?&XP=4sv&<A1W
zVT;3l3@3$$g;$0@j&O)r8qqPAHFwe6Lv!Cm`b3sQ-kWDJPdTqGN;N7zsxE3g+Bdp1
zx<AG)W?9VDSe;l&Y)c$DE-J1zZfw5a{O$9H;+^6P<9ipFFUVbRd7;k2^o6GusV)*M
zI+j38h)y_^@IeqNs1}SR@)LI@jtY6g9l~cKFVQy9h}c71DjrVqNGeTwlI)SZHF+e(
zGo>u$xr8UFki1L{Ox>G0o)(&RAZ;=|I=wN2l97;cLaHH6leTB-XXa*h%dBOEvi`+x
zi?=Txl?TadvyiL>SuF~-LZ;|cS}4~l2eM~nS7yJ>iOM;atDY;(?aZ^v+mJV$@1Ote
z62cPUlD4IWOIIx&SmwQ~YB{nzae3Pc;}r!fhE@iwJh+OsDs9zItL;~pu715HdQEGA
zUct(O!L<Qv>kCy1<%NCg+}G`0PgpNm-?d@-hMgNe6^V+j6x$b<6@S<$+<4_1hi}Ti
zncS4LsjI}fWY1>OX6feMEuLErma3QLmkw?X+1j)X-&VBk_4Y;EFPF_I+q;9dL%E~B
zJh;4Nr^(LEJ3myURP<E(R5tF?-L+xY_-@he8+*L=H0;&eTfF!EKFPk@RRL8^)n?UY
z`$_w=_dl+Qs_FQa`)ysVPHl1R#{<#>{Rblsw%57T)g973R8o)DE9*xN#~;4_o$q%o
z4K@u`jhx2fBXC4{<mvYb-}fF3I@)%Od#vFH(;s#nXB{tULYnfLMw?Tb`&(jLx=+kL
z(bnqTdi+P*9}k=~JXv{4^Hj-c+UbJRlV|eJjGdL8eSR+a++f?HwtMGe&fjVeZ|}Mg
zbm7uP|BL54ygSZZ^0;*JvfJeoSGZT2uR33C>U8Qn{*%*B$Ge=nny$HAYq{=vy|sI0
z_vss+H_qMky?OB#|JK!>IX&II^LlUh#rO5!7TtbwC;iULyV-Xq?ybB}ykGP{?LpZ?
z-G|jbTmIbG@7#ZCz;~eY(cDM(28Dyq{*m>M4?_iynUBkc4TkHUI6gT!;y-fz>HMcd
z&t%Ugo)`Y2{>!cx7B7DI)$7;J(U{Spm-3gBzioV_{p!H$8L!*M!p0uH$#^p{Ui4P`
z?ZJ24cOCDe-w#jZd?0@)|7iKK^;6KN`;!@ylm7$*nDhK&GcDTy000JJOGiWi{{a60
z|De66lK=n!32;bRa{vGf6951U69E94oEQKA00(qQO+^RV1_c!dETEeU!~g&S-$_J4
zR5;6pkzZ)mWfaH1=RD8vxA*n$>|#y=wG}!hI;Ry<h}2CGNQiXnML~E`poGkFXy8SO
z8I4Hj&o0z1Uc#s$g`3^X910_C4%w!|#@@|8d*^h%e|-0Qp647derwo;_2pa~IA6Z!
zb2x-Kz0`UYeMdF`*h=qroP2)8vgkP{x^mWORzz>jRD8bs%7c-c$2Z@{6Cwa;{NOT%
zzS;z|oNGAQ-ke)imt9kFva~!aC{+cOBmfE*8=5%PQ#jspsOjkTBSSdT+6dZlbQnMH
zTZ`S_-F)$lmfGHi`fPM}#-ox1loL?Z2}BhkD7>gXlQq;k_;AnH@2qa0C&2a#4ZX*j
z2NOj+Sqxwz1Q93^Ac~+s5Y@yhc`v#sX6o#_xA*j(HD3|{{M0vnX;oe3<>_*uM^4l$
z5i<Zy?@YG?&I?>nBwmzNZ=Cpja<gsA<)2-cH4TMQz^qpg5oIF+a|)*lgdlJMU}6x7
ziV}H;`d6El)Y||oFU{%_V}*=i#D)+>3}yn&1-L-qARqz&CRM=skTC|ewp<OFaw4`i
zwumhuju??8L?#Uo1&n7T3=kwGQif#-q~z>$(G{GRvSnIq4G<ZkOvH$6N+F^!EPw-4
z0BZu`02R>(QxB`R_(Fdne?4EBu$IBhWDRR%2{kdHCI)I^AdXWiYgnyeHI`_2taS0)
z_g*OQ==ZNw$8MKeFJGTQ2nxd>VuCS*OpW=6L=6)#SA%~SZ-23C^-cib1LqXE51Y<h
z9hrG+bfT<dg({dxeE_^y00he*5$FO|`t8!>(24Hx768D;&h*c9yUwT0w(gCecaC3d
z@48zWxaVYG%IUAyib<~Te(}^Fg^?}$|N0D1Q}aio^L^Wo`LloCN%WJ``K~t)_iugs
z(}8t({cP>LVMWJNbFlN+aN{>UQ{x}!#=5Znmqq`czKj3WwuAlkueDuiMD~Xm0I<B{
bKmCsZzk6ggYXo`_00000NkvXXu0mjfg2suj

literal 0
HcmV?d00001

diff --git a/sphinx/themes/basic/static/down-pressed.png b/sphinx/themes/basic/static/down-pressed.png
new file mode 100644
index 0000000000000000000000000000000000000000..6f7ad782782e4f8e39b0c6e15c7344700cdd2527
GIT binary patch
literal 368
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`jKx9jP7LeL$-D$|*pj^6U4S$Y
z{B+)352QE?JR*yM+OLB!qm#z$3ZNi+iKnkC`z>}Z23@f-Ava~9&<9T!#}JFtXD=!G
zGdl{fK6ro2OGiOl+hKvH6i=D3%%Y^j`yIkRn!8O>@bG)IQR0{Kf+mxNd=_WScA8u_
z3;8(7x2){m9`nt+U(Nab&1G)!{`SPVpDX$w8McLTzAJ39wprG3p4XLq$06M`%}2Yk
zRPPsb<eOBuJzzJtaBsDHruj&MO}CkI9@oM{u93MWs^*chA=$e7rUh<GoTlU#?wGGz
z*_K*(>ES*dnYm1wkGL;iioAUB*Or2kz6(-M_r_#Me-<g+a_(*JjN&U*z02OX#~$%(
z6#3ZLekrlFz3AKX``cC&$K^ccDa(j?XLM8b!=w9;#rq6gQ-fH_ZUFtx;OXk;vd$@?
F2>`{mj$Z%(

literal 0
HcmV?d00001

diff --git a/sphinx/themes/basic/static/down.png b/sphinx/themes/basic/static/down.png
new file mode 100644
index 0000000000000000000000000000000000000000..3003a88770de3977d47a2ba69893436a2860f9e7
GIT binary patch
literal 363
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`jKx9jP7LeL$-D$|*pj^6U4S$Y
z{B+)352QE?JR*yM+OLB!qm#z$3ZNi+iKnkC`z>}xaV3tUZ$qnrLa#kt978NlpS`ru
z&)HFc^}^>{UOEce+71h5nn>6&w6A!ie<Ab_+oUB-{c$>Nbu1wh)UGh{8~et^#oZ1#
z>T7oM=FZ~xXWnTo{qnXm$ZLOlqGswI_m2{XwVK)IJmBjW{J3-B3x@C=M{ShWt#<pw
z+y29?H~r3Ic5@5&Ry#4lLZ0TfgDn1@D+(sA?zAeN{MGSl)<;wKn{AaYbJjJ-X;-#|
zTD>fYS9M?R;8K$~YwlIqwf>VA7q=YKcwf2DS4Zj5inDKXXB1zl=(YO3ST6~rDq)&z
z*o>z)=hxrfG-cDBW0G$!?6{M<$@{_4{m1o%Ub!naEtn|@^frU1tDnm{r-UW|!^@B8

literal 0
HcmV?d00001

diff --git a/sphinx/themes/basic/static/up-pressed.png b/sphinx/themes/basic/static/up-pressed.png
new file mode 100644
index 0000000000000000000000000000000000000000..8bd587afee2fe38989383ff82010147ea56b93dd
GIT binary patch
literal 372
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`jKx9jP7LeL$-D$|*pj^6U4S$Y
z{B+)352QE?JR*yM+OLB!qm#z$3ZNi+iKnkC`z>}Z1|5lxjZvvUp)Z~;jv*GO&raT-
z#pEb(tbY1#Ey4dH;Y+=<pEBRLsjGAOCY!v|CyvUA4wrPfZ{O_DPe^{q91)qJXqI&@
zO~JiL+CN7oqU^@cvS+{3Bz9yAOB-!e{LTNlK+)ab|H>wAPPMA->(Ug=YM6W%tgKtA
zI`O=0Laf#Y-Y4f~`^K_)D_mvj{B=4?=t!I41ZLNlI~j_4kE*^nvF$)|>mH^X%(>6c
z8XimFvvIAOoRJf!>6jzIa5w(S%7lxdZ{*qJxhxpj6S#UB!oTuMX^Z^6%)IfT_v-!3
z=PEaM_iSh6_`s$!$NaEMP6gw<x#pX-zc1lmBOrZAdYY~+^N*K~{#DY`%7Ol8@O1Ta
JS?83{1OR?3hMxcc

literal 0
HcmV?d00001

diff --git a/sphinx/themes/basic/static/up.png b/sphinx/themes/basic/static/up.png
new file mode 100644
index 0000000000000000000000000000000000000000..b94625680b4a4b9647c3a6f3f283776930696aa9
GIT binary patch
literal 363
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`jKx9jP7LeL$-D$|*pj^6U4S$Y
z{B+)352QE?JR*yM+OLB!qm#z$3ZNi+iKnkC`z>}xaYa3wv(2tRq1T=+jv*GO&raUx
z$K)u`w*Tuor>1}ySNCesuPuG-8#b%jw0sn-5fpk^!623V@1GR6+<`78?&Rhov&jx6
z*R7KttIVGJ=8yH~|HhI(uB&NIpYp$LXT}M`Z<Dv|Q9O9-{p!t<9#srg4(I=_Xg%_r
zaf7X90Rxxu?X9UB7>)D=?%dxpN#UiKM#HZsJK4DUm#Y3a5!dMF634rTxz_l%hvABb
z(=Pc<$5*Xj@eE$@$89c0_oa>Y5;`&;INvn7C-9xQbH92`*_(~*lcvS}m5Z2pGdgKc
z>;tJC%=6B^QS*>ubT+QGD)v`9z&&Y`y-xHu*7vDC$|9@xfdY)d)78&qol`;+01iQm
A<^TWy

literal 0
HcmV?d00001


From ed33f6866dc6b667300a661842c592cfbb57f629 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Sun, 8 Aug 2010 15:39:56 -0500
Subject: [PATCH 088/127] only provide pygments.css, update image locations.

---
 sphinx/builders/websupport.py            | 14 +++-----------
 sphinx/themes/basic/static/websupport.js | 12 ++++++------
 sphinx/websupport/__init__.py            |  9 +++++++++
 sphinx/writers/websupport.py             |  3 +++
 4 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index cdd0fb925..3d0356b71 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -81,9 +81,11 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
                       ctx, event_arg)
 
         # Create a dict that will be pickled and used by webapps.
+        css = '<link rel="stylesheet" href="%s" type=text/css />' % \
+            pathto('_static/pygmentcs.css', 1)
         doc_ctx = {'body': ctx.get('body', ''),
                    'title': ctx.get('title', ''),
-                   'css': self._make_css(ctx),
+                   'css': css,
                    'js': self._make_js(ctx)}
         # Partially render the html template to proved a more useful ctx.
         template = self.templates.environment.get_template(templatename)
@@ -124,16 +126,6 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     def dump_search_index(self):
         self.indexer.finish_indexing()
 
-    def _make_css(self, ctx):
-        def make_link(file):
-            path = ctx['pathto'](file, 1)
-            return '<link rel="stylesheet" href="%s" type=text/css />' % path
-
-        links = [make_link('_static/pygments.css')]
-        for file in ctx['css_files']:
-            links.append(make_link(file))
-        return '\n'.join(links)
-
     def _make_js(self, ctx):
         def make_script(file):
             path = ctx['pathto'](file, 1)
diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 0e2b44303..aeef3ece1 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -615,7 +615,7 @@
     return this.each(function() {
       $(this).append(
 	$('<a href="#" class="sphinx_comment"></a>')
-	  .html(opts.commentHTML)
+	  .html('<img src="' + opts.commentImage + '" alt="comment" />')
 	  .click(function(event) {
 	    event.preventDefault();
 	    show($(this).parent().attr('id'));
@@ -722,11 +722,11 @@
     acceptCommentURL: '/accept_comment',
     rejectCommentURL: '/reject_comment',
     rejectCommentURL: '/delete_comment',
-    commentHTML: '<img src="/static/comment.png" alt="comment" />',
-    upArrow: '/static/up.png',
-    downArrow: '/static/down.png',
-    upArrowPressed: '/static/up-pressed.png',
-    downArrowPressed: '/static/down-pressed.png',
+    commentImage: '/static/_static/comment.png',
+    upArrow: '/static/_static/up.png',
+    downArrow: '/static/_static/down.png',
+    upArrowPressed: '/static/_static/up-pressed.png',
+    downArrowPressed: '/static/_static/down-pressed.png',
     voting: false,
     moderator: false
   }, COMMENT_OPTIONS);
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 9bd6cbda5..3215e856e 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -162,6 +162,15 @@ class WebSupport(object):
                                                           'reject_comment'))
             parts.append('deleteCommentURL: "/%s/%s",' % (self.docroot, 
                                                           'delete_comment'))
+
+        if self.staticdir != 'static':
+            p = lambda file: '%s/_static/%s' % (self.staticdir, file)
+            parts.append('commentImage: "/%s",' % p('comment.png') )
+            parts.append('upArrow: "/%s",' % p('up.png'))
+            parts.append('downArrow: "/%s",' % p('down.png'))
+            parts.append('upArrowPressed: "/%s",' % p('up-pressed.png'))
+            parts.append('downArrowPressed: "/%s",' % p('down-pressed.png'))
+            
         if username is not '':
             parts.append('voting: true,')
             parts.append('username: "%s",' % username)
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 63281f182..688fdbeaf 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -62,4 +62,7 @@ class WebSupportTranslator(HTMLTranslator):
                                       line=node.line,
                                       source=node.rawsource,
                                       treeloc='???')
+        if db_node_id == 30711:
+            import pdb
+            pdb.set_trace()
         return db_node_id

From 978afa9c0df9ceba20f99c94dc5f3c82de87afd9 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 10:10:11 -0500
Subject: [PATCH 089/127] only comment on paragraphs

---
 .../websupport/storage/sqlalchemystorage.py   |  2 +-
 sphinx/writers/websupport.py                  | 20 +++++++------------
 2 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
index 02fa33b50..2e182311e 100644
--- a/sphinx/websupport/storage/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -31,7 +31,7 @@ class SQLAlchemyStorage(StorageBackend):
         node = Node(document, line, source, treeloc)
         self.build_session.add(node)
         self.build_session.flush()
-        return node.id
+        return node
 
     def post_build(self):
         self.build_session.commit()
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 688fdbeaf..64a431d8e 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -15,7 +15,7 @@ class WebSupportTranslator(HTMLTranslator):
     """
     Our custom HTML translator.
     """
-    commentable_nodes = ['bullet_list', 'paragraph', 'desc']
+    commentable_nodes = ['paragraph']
 
     def __init__(self, builder, *args, **kwargs):
         HTMLTranslator.__init__(self, builder, *args, **kwargs)
@@ -23,8 +23,7 @@ class WebSupportTranslator(HTMLTranslator):
         self.init_support()
 
     def init_support(self):
-        self.in_commentable = False
-        self.current_id = 0
+        self.cur_node = None
 
     def dispatch_visit(self, node):
         if node.__class__.__name__ in self.commentable_nodes:
@@ -39,30 +38,25 @@ class WebSupportTranslator(HTMLTranslator):
     def handle_visit_commentable(self, node):
         # If this node is nested inside another commentable node this
         # node will not be commented.
-        if not self.in_commentable:
-            self.in_commentable = True
-            node_id = self.add_db_node(node)
+        if self.cur_node is None:
+            self.cur_node = self.add_db_node(node)
             # We will place the node in the HTML id attribute. If the node
             # already has an id (for indexing purposes) put an empty
             # span with the existing id directly before this node's HTML.
             if node.attributes['ids']:
                 self.body.append('<span id="%s"></span>'
                                  % node.attributes['ids'][0])
-            node.attributes['ids'] = ['s%s' % node_id]
+            node.attributes['ids'] = ['s%s' % self.cur_node.id]
             node.attributes['classes'].append(self.comment_class)
 
     def handle_depart_commentable(self, node):
-        assert(self.in_commentable)
         if self.comment_class in node.attributes['classes']:
-            self.in_commentable = False
+            self.cur_node = None
 
     def add_db_node(self, node):
         storage = self.builder.app.storage
         db_node_id = storage.add_node(document=self.builder.cur_docname,
                                       line=node.line,
-                                      source=node.rawsource,
+                                      source=node.rawsource or node.astext(),
                                       treeloc='???')
-        if db_node_id == 30711:
-            import pdb
-            pdb.set_trace()
         return db_node_id

From ac066fb54a15cc1e6a6b8e670b9f2446c6a94ffe Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 14:22:31 -0500
Subject: [PATCH 090/127] updated docs

---
 doc/web/api.rst                               |  43 +++-
 doc/web/frontend.rst                          |   6 -
 doc/web/quickstart.rst                        | 142 ++++++++----
 doc/web/searchadapters.rst                    |   2 +-
 doc/web/storagebackends.rst                   |  26 +++
 doc/websupport.rst                            |   1 -
 sphinx/websupport/__init__.py                 | 203 +++++++++++-------
 sphinx/websupport/search/__init__.py          |  33 ++-
 sphinx/websupport/storage/__init__.py         |  85 ++++++--
 sphinx/websupport/storage/db.py               |   3 +-
 .../websupport/storage/sqlalchemystorage.py   |   8 +-
 sphinx/writers/websupport.py                  |   3 +-
 12 files changed, 384 insertions(+), 171 deletions(-)
 delete mode 100644 doc/web/frontend.rst

diff --git a/doc/web/api.rst b/doc/web/api.rst
index fcd0513ee..b2b7ef952 100644
--- a/doc/web/api.rst
+++ b/doc/web/api.rst
@@ -10,10 +10,45 @@ The WebSupport Class
    The main API class for the web support package. All interactions
    with the web support package should occur through this class.
 
-   :param srcdir: the directory containing the reStructuredText files
-   :param outdir: the directory in which to place the built data
-   :param search: the search system to use
-   :param comments: an instance of a CommentBackend
+   The class takes the following keyword arguments:
+
+   srcdir
+       The directory containing reStructuredText source files.
+
+   builddir
+       The directory that build data and static files should be placed in.
+       This should be used when creating a :class:`WebSupport` object that
+       will be used to build data.
+
+   datadir:
+       The directory that the web support data is in. This should be used
+       when creating a :class:`WebSupport` object that will be used to
+       retrieve data.
+
+   search:
+       This may contain either a string (e.g. 'xapian') referencing a
+       built-in search adapter to use, or an instance of a subclass of
+       :class:`~sphinx.websupport.search.BaseSearch`.
+
+   storage:
+       This may contain either a string representing a database uri, or an
+       instance of a subclass of 
+       :class:`~sphinx.websupport.storage.StorageBackend`. If this is not
+       provided a new sqlite database will be created.
+
+   moderation_callback:
+       A callable to be called when a new comment is added that is not
+       displayed. It must accept one argument: a dict representing the 
+       comment that was added.
+
+   staticdir:
+       If static files are served from a location besides "/static", this
+       should be a string with the name of that location
+       (e.g. '/static_files').
+
+   docroot:
+       If the documentation is not served from the base path of a URL, this
+       should be a string specifying that path (e.g. 'docs')
     
 Methods
 ~~~~~~~
diff --git a/doc/web/frontend.rst b/doc/web/frontend.rst
deleted file mode 100644
index 5ffe16674..000000000
--- a/doc/web/frontend.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-.. _websupportfrontend:
-
-Web Support Frontend
-====================
-
-More coming soon.
\ No newline at end of file
diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
index b0a60507a..302a4db0e 100644
--- a/doc/web/quickstart.rst
+++ b/doc/web/quickstart.rst
@@ -7,26 +7,26 @@ Building Documentation Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To make use of the web support package in your application you'll
-need to build that data it uses. This data includes pickle files representing
+need to build the data it uses. This data includes pickle files representing
 documents, search indices, and node data that is used to track where
 comments and other things are in a document. To do this you will need
-to create an instance of the :class:`~sphinx.websupport.api.WebSupport` 
+to create an instance of the :class:`~sphinx.websupport.WebSupport` 
 class and call it's :meth:`~sphinx.websupport.WebSupport.build` method::
 
     from sphinx.websupport import WebSupport
 
     support = WebSupport(srcdir='/path/to/rst/sources/',
-                         outdir='/path/to/build/outdir',
+                         builddir='/path/to/build/outdir',
 		         search='xapian')
 
     support.build()
 
 This will read reStructuredText sources from `srcdir` and place the
-necessary data in `outdir`. This directory contains all the data needed
+necessary data in `builddir`. The `builddir` will contain two 
+sub-directories. One named "data" that contains all the data needed
 to display documents, search through documents, and add comments to
-documents. It will also contain a subdirectory named "static", which
-contains static files. These files will be linked to by Sphinx documents,
-and should be served from "/static".
+documents. The other directory will be called "static" and contains static 
+files that should be served from "/static".
 
 .. note::
 
@@ -37,7 +37,7 @@ and should be served from "/static".
 Integrating Sphinx Documents Into Your Webapp
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now that you have the data, it's time to do something useful with it.
+Now that the data is built, it's time to do something useful with it.
 Start off by creating a :class:`~sphinx.websupport.WebSupport` object
 for your application::
     
@@ -59,8 +59,8 @@ This will return a dictionary containing the following items:
 * **sidebar**: The sidebar of the document as HTML  
 * **relbar**: A div containing links to related documents
 * **title**: The title of the document
-* **DOCUMENTATION_OPTIONS**: Javascript containing documentation options
-* **COMMENT_OPTIONS**: Javascript containing comment options
+* **css**: Links to css files used by Sphinx
+* **js**: Javascript containing comment options
 
 This dict can then be used as context for templates. The goal is to be
 easy to integrate with your existing templating system. An example using 
@@ -74,13 +74,15 @@ easy to integrate with your existing templating system. An example using
       {{ document.title }}
     {%- endblock %}
 
-    {%- block js %}
-      <script type="text/javascript">
-        {{ document.DOCUMENTATION_OPTIONS|safe }}
-	{{ document.COMMENT_OPTIONS|safe }}
-      </script>
+    {% block css %}
       {{ super() }}
-      <script type="text/javascript" src="/static/websupport.js"></script>
+      {{ document.css|safe }}
+      <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
+    {% endblock %}
+
+    {%- block js %}
+      {{ super() }}
+      {{ document.js|safe }}
     {%- endblock %}
 
     {%- block relbar %}
@@ -99,12 +101,12 @@ Authentication
 --------------
 
 To use certain features such as voting it must be possible to authenticate
-users. The details of the authentication are left to the your application.
+users. The details of the authentication are left to your application.
 Once a user has been authenticated you can pass the user's details to certain
 :class:`~sphinx.websupport.WebSupport` methods using the *username* and
 *moderator* keyword arguments. The web support package will store the
 username with comments and votes. The only caveat is that if you allow users
-to change their username, you must update the websupport package's data::
+to change their username you must update the websupport package's data::
 
    support.update_username(old_username, new_username)
 
@@ -113,18 +115,22 @@ should be a boolean representing whether the user has moderation
 privilieges. The default value for *moderator* is *False*.
 
 An example `Flask <http://flask.pocoo.org/>`_ function that checks whether
-a user is logged in, and the retrieves a document is::
+a user is logged in and then retrieves a document is::
+
+    from sphinx.websupport.errors import *
 
     @app.route('/<path:docname>')
     def doc(docname):
-        if g.user:
-	    document = support.get_document(docname, g.user.name,
-	                                    g.user.moderator)
-	else:
-	    document = support.get_document(docname)
+    	username = g.user.name if g.user else ''
+	moderator = g.user.moderator if g.user else False
+	try:
+	    document = support.get_document(docname, username, moderator)
+	except DocumentNotFoundError:
+	    abort(404)
         return render_template('doc.html', document=document)
 
 The first thing to notice is that the *docname* is just the request path.
+This makes accessing the correct document easy from a single view.
 If the user is authenticated then the username and moderation status are
 passed along with the docname to 
 :meth:`~sphinx.websupport.WebSupport.get_document`. The web support package
@@ -134,8 +140,12 @@ will then add this data to the COMMENT_OPTIONS that are used in the template.
 
    This only works works if your documentation is served from your
    document root. If it is served from another directory, you will
-   need to prefix the url route with that directory::
-
+   need to prefix the url route with that directory, and give the `docroot`
+   keyword argument when creating the web support object::
+   
+       support = WebSupport(...
+                            docroot='docs')
+   
        @app.route('/docs/<path:docname>')
 
 Performing Searches
@@ -160,8 +170,8 @@ did to render our documents. That's because
 dict in the same format that
 :meth:`~sphinx.websupport.WebSupport.get_document` does.
 
-Comments
-~~~~~~~~
+Comments & Proposals
+~~~~~~~~~~~~~~~~~~~~
 
 Now that this is done it's time to define the functions that handle
 the AJAX calls from the script. You will need three functions. The first
@@ -171,20 +181,29 @@ function is used to add a new comment, and will call the web support method
     @app.route('/docs/add_comment', methods=['POST'])
     def add_comment():
         parent_id = request.form.get('parent', '')
+        node_id = request.form.get('node', '')
         text = request.form.get('text', '')
+        proposal = request.form.get('proposal', '')
         username = g.user.name if g.user is not None else 'Anonymous'
-        comment = support.add_comment(parent_id, text, username=username)
+        comment = support.add_comment(text, node_id='node_id',
+	                              parent_id='parent_id', 
+				      username=username, proposal=proposal)
         return jsonify(comment=comment)
 
-Then next function handles the retrieval of comments for a specific node, 
-and is aptly named :meth:`~sphinx.websupport.WebSupport.get_data`::
+You'll notice that both a `parent_id` and `node_id` are sent with the
+request. If the comment is being attached directly to a node, `parent_id`
+will be empty. If the comment is a child of another comment, then `node_id`
+will be empty. Then next function handles the retrieval of comments for a 
+specific node, and is aptly named 
+:meth:`~sphinx.websupport.WebSupport.get_data`::
 
     @app.route('/docs/get_comments')
     def get_comments():
-        user_id = g.user.id if g.user else None
-        parent_id = request.args.get('parent', '')
-        comments = support.get_data(parent_id, user_id)
-        return jsonify(comments=comments)
+        username = g.user.name if g.user else None
+	moderator = g.user.moderator if g.user else False
+	node_id = request.args.get('node', '')
+        data = support.get_data(parent_id, user_id)
+        return jsonify(**data)
 
 The final function that is needed will call
 :meth:`~sphinx.websupport.WebSupport.process_vote`, and will handle user
@@ -201,12 +220,49 @@ votes on comments::
         support.process_vote(comment_id, g.user.id, value)
         return "success"
 
-.. note::
+Comment Moderation
+~~~~~~~~~~~~~~~~~~
 
-   Authentication is left up to your existing web application. If you do
-   not have an existing authentication system there are many readily 
-   available for different frameworks. The web support system stores only
-   the user's unique integer `user_id` and uses this both for storing votes 
-   and retrieving vote information. It is up to you to ensure that the 
-   user_id passed in is unique, and that the user is authenticated. The 
-   default backend will only allow one vote per comment per `user_id`.
+By default all comments added through 
+:meth:`~sphinx.websupport.WebSupport.add_comment` are automatically
+displayed. If you wish to have some form of moderation, you can pass
+the `displayed` keyword argument::
+
+    comment = support.add_comment(text, node_id='node_id',
+                                  parent_id='parent_id', 
+                                  username=username, proposal=proposal,
+ 				  displayed=False)
+
+You can then create two new views to handle the moderation of comments. The
+first will be called when a moderator decides a comment should be accepted
+and displayed::
+
+    @app.route('/docs/accept_comment', methods=['POST'])
+    def accept_comment():
+        moderator = g.user.moderator if g.user else False
+	comment_id = request.form.get('id')
+	support.accept_comment(comment_id, moderator=moderator)
+	return 'OK'
+
+The next is very similar, but used when rejecting a comment::
+
+    @app.route('/docs/reject_comment', methods=['POST'])
+    def reject_comment():
+        moderator = g.user.moderator if g.user else False
+	comment_id = request.form.get('id')
+	support.reject_comment(comment_id, moderator=moderator)
+	return 'OK'
+
+To perform a custom action (such as emailing a moderator) when a new comment
+is added but not displayed, you can pass callable to the
+:class:`~sphinx.websupport.WebSupport` class when instantiating your support
+object::
+
+    def moderation_callback(comment):
+        Do something...
+
+    support = WebSupport(...
+                         moderation_callback=moderation_callback)
+
+The moderation callback must take one argument, which will be the same
+comment dict that is returned by add_comment.
\ No newline at end of file
diff --git a/doc/web/searchadapters.rst b/doc/web/searchadapters.rst
index 83e928baa..e03fee81f 100644
--- a/doc/web/searchadapters.rst
+++ b/doc/web/searchadapters.rst
@@ -11,7 +11,7 @@ and pass that as the `search` keyword argument when you create the
 :class:`~sphinx.websupport.WebSupport` object::
 
    support = Websupport(srcdir=srcdir,
-                        outdir=outdir,
+                        builddir=builddir,
 			search=MySearch())
 
 For more information about creating a custom search adapter, please see
diff --git a/doc/web/storagebackends.rst b/doc/web/storagebackends.rst
index 4a10e1090..6411bf176 100644
--- a/doc/web/storagebackends.rst
+++ b/doc/web/storagebackends.rst
@@ -5,6 +5,22 @@
 Storage Backends
 ================
 
+To create a custom storage backend you will need to subclass the
+:class:`~StorageBackend` class. Then create an instance of the new class
+and pass that as the `storage` keyword argument when you create the
+:class:`~sphinx.websupport.WebSupport` object::
+
+   support = Websupport(srcdir=srcdir,
+                        builddir=builddir,
+			storage=MyStorage())
+
+For more information about creating a custom storage backend, please see
+the documentation of the :class:`StorageBackend` class below.
+
+.. class:: StorageBackend
+
+   Defines an interface for storage backends.
+
 StorageBackend Methods
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -16,4 +32,14 @@ StorageBackend Methods
 
 .. automethod:: sphinx.websupport.storage.StorageBackend.add_comment
 
+.. automethod:: sphinx.websupport.storage.StorageBackend.delete_comment
+
 .. automethod:: sphinx.websupport.storage.StorageBackend.get_data
+
+.. automethod:: sphinx.websupport.storage.StorageBackend.process_vote
+
+.. automethod:: sphinx.websupport.storage.StorageBackend.update_username
+
+.. automethod:: sphinx.websupport.storage.StorageBackend.accept_comment
+
+.. automethod:: sphinx.websupport.storage.StorageBackend.reject_comment
\ No newline at end of file
diff --git a/doc/websupport.rst b/doc/websupport.rst
index c7833e7ab..59973d745 100644
--- a/doc/websupport.rst
+++ b/doc/websupport.rst
@@ -11,6 +11,5 @@ into your web application. To learn more read the
 
    web/quickstart
    web/api
-   web/frontend
    web/searchadapters
    web/storagebackends
\ No newline at end of file
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 3215e856e..38ebd2340 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -52,6 +52,8 @@ class WebSupport(object):
         self._init_search(search)            
         self._init_storage(storage)
 
+        self._make_base_comment_options()
+
     def _init_storage(self, storage):
         if isinstance(storage, StorageBackend):
             self.storage = storage
@@ -90,11 +92,11 @@ class WebSupport(object):
         """Build the documentation. Places the data into the `outdir`
         directory. Use it like this::
 
-            support = WebSupport(srcdir, outdir, search='xapian')
+            support = WebSupport(srcdir, builddir, search='xapian')
             support.build()
 
-        This will read reStructured text files from `srcdir`. Then it
-        build the pickles and search index, placing them into `outdir`.
+        This will read reStructured text files from `srcdir`. Then it will
+        build the pickles and search index, placing them into `builddir`.
         It will also save node data to the database.
         """
         if not self.srcdir:
@@ -116,7 +118,7 @@ class WebSupport(object):
         be a dict object which can be used to render a template::
 
             support = WebSupport(datadir=datadir)
-            support.get_document('index')
+            support.get_document('index', username, moderator)
             
         In most cases `docname` will be taken from the request path and 
         passed directly to this function. In Flask, that would be something
@@ -124,13 +126,28 @@ class WebSupport(object):
 
             @app.route('/<path:docname>')
             def index(docname):
-                q = request.args.get('q')
-                document = support.get_search_results(q)
+                username = g.user.name if g.user else ''
+                moderator = g.user.moderator if g.user else False
+                try:
+                    document = support.get_document(docname, username,
+                                                    moderator)
+                except DocumentNotFoundError:
+                    abort(404)
                 render_template('doc.html', document=document)
 
         The document dict that is returned contains the following items
         to be used during template rendering.
 
+        * **body**: The main body of the document as HTML
+        * **sidebar**: The sidebar of the document as HTML  
+        * **relbar**: A div containing links to related documents
+        * **title**: The title of the document
+        * **css**: Links to css files used by Sphinx
+        * **js**: Javascript containing comment options
+
+        This raises :class:`~sphinx.websupport.errors.DocumentNotFoundError`
+        if a document matching `docname` is not found.
+
         :param docname: the name of the document to load.
         """
         infilename = path.join(self.datadir, 'pickles', docname + '.fpickle')
@@ -146,39 +163,6 @@ class WebSupport(object):
         document['js'] = comment_opts + '\n' + document['js']
         return document
 
-    def _make_comment_options(self, username, moderator):
-        parts = ['<script type="text/javascript">', 
-                 'var COMMENT_OPTIONS = {']
-        if self.docroot is not '':
-            parts.append('addCommentURL: "/%s/%s",' % (self.docroot, 
-                                                       'add_comment'))
-            parts.append('getCommentsURL: "/%s/%s",' % (self.docroot, 
-                                                        'get_comments'))
-            parts.append('processVoteURL: "/%s/%s",' % (self.docroot, 
-                                                        'process_vote'))
-            parts.append('acceptCommentURL: "/%s/%s",' % (self.docroot, 
-                                                          'accept_comment'))
-            parts.append('rejectCommentURL: "/%s/%s",' % (self.docroot, 
-                                                          'reject_comment'))
-            parts.append('deleteCommentURL: "/%s/%s",' % (self.docroot, 
-                                                          'delete_comment'))
-
-        if self.staticdir != 'static':
-            p = lambda file: '%s/_static/%s' % (self.staticdir, file)
-            parts.append('commentImage: "/%s",' % p('comment.png') )
-            parts.append('upArrow: "/%s",' % p('up.png'))
-            parts.append('downArrow: "/%s",' % p('down.png'))
-            parts.append('upArrowPressed: "/%s",' % p('up-pressed.png'))
-            parts.append('downArrowPressed: "/%s",' % p('down-pressed.png'))
-            
-        if username is not '':
-            parts.append('voting: true,')
-            parts.append('username: "%s",' % username)
-        parts.append('moderator: %s' % str(moderator).lower())
-        parts.append('};')
-        parts.append('</script>')
-        return '\n'.join(parts)            
-
     def get_search_results(self, q):
         """Perform a search for the query `q`, and create a set
         of search results. Then render the search results as html and
@@ -200,37 +184,42 @@ class WebSupport(object):
 
     def get_data(self, node_id, username=None, moderator=False):
         """Get the comments and source associated with `node_id`. If 
-        `user_id` is given vote information will be included with the 
-        returned comments. The default CommentBackend returns dict with
-        two keys, *source*, and *comments*. *comments* is a list of
-        dicts that represent a comment, each having the following items:
+        `username` is given vote information will be included with the 
+        returned comments. The default CommentBackend returns a dict with
+        two keys, *source*, and *comments*. *source* is raw source of the
+        node and is used as the starting point for proposals a user can
+        add. *comments* is a list of dicts that represent a comment, each 
+        having the following items:
 
-        ============ ======================================================
-        Key          Contents
-        ============ ======================================================
-        text         The comment text.
-        username     The username that was stored with the comment.
-        id           The comment's unique identifier.
-        rating       The comment's current rating.
-        age          The time in seconds since the comment was added.
-        time         A dict containing time information. It contains the
-                     following keys: year, month, day, hour, minute, second,
-                     iso, and delta. `iso` is the time formatted in ISO
-                     8601 format. `delta` is a printable form of how old
-                     the comment is (e.g. "3 hours ago").
-        vote         If `user_id` was given, this will be an integer
-                     representing the vote. 1 for an upvote, -1 for a 
-                     downvote, or 0 if unvoted.
-        node         The node that the comment is attached to. If the
-                     comment's parent is another comment rather than a
-                     node, this will be null.
-        parent       The id of the comment that this comment is attached 
-                     to if it is not attached to a node.
-        children     A list of all children, in this format.
-        ============ ======================================================
+        ============= ======================================================
+        Key           Contents
+        ============= ======================================================
+        text          The comment text.
+        username      The username that was stored with the comment.
+        id            The comment's unique identifier.
+        rating        The comment's current rating.
+        age           The time in seconds since the comment was added.
+        time          A dict containing time information. It contains the
+                      following keys: year, month, day, hour, minute, second,
+                      iso, and delta. `iso` is the time formatted in ISO
+                      8601 format. `delta` is a printable form of how old
+                      the comment is (e.g. "3 hours ago").
+        vote          If `user_id` was given, this will be an integer
+                      representing the vote. 1 for an upvote, -1 for a 
+                      downvote, or 0 if unvoted.
+        node          The id of the node that the comment is attached to. 
+                      If the comment's parent is another comment rather than 
+                      a node, this will be null.
+        parent        The id of the comment that this comment is attached 
+                      to if it is not attached to a node.
+        children      A list of all children, in this format.
+        proposal_diff An HTML representation of the differences between the
+                      the current source and the user's proposed source.
+        ============= ======================================================
 
         :param node_id: the id of the node to get comments for.
-        :param user_id: the id of the user viewing the comments.
+        :param username: the username of the user viewing the comments.
+        :param moderator: whether the user is a moderator.
         """
         return self.storage.get_data(node_id, username, moderator)
 
@@ -243,6 +232,10 @@ class WebSupport(object):
         `moderator` is False, the comment will only be deleted if the
         `username` matches the `username` on the comment.
 
+        This raises :class:`~sphinx.websupport.errors.UserNotAuthorizedError`
+        if moderator is False and `username` doesn't match username on the
+        comment.
+
         :param comment_id: the id of the comment to delete.
         :param username: the username requesting the deletion.
         :param moderator: whether the requestor is a moderator.
@@ -250,19 +243,19 @@ class WebSupport(object):
         self.storage.delete_comment(comment_id, username, moderator)
 
     def add_comment(self, text, node_id='', parent_id='', displayed=True, 
-                    username=None, rating=0, time=None, proposal=None,
+                    username=None, time=None, proposal=None,
                     moderator=False):
         """Add a comment to a node or another comment. Returns the comment 
         in the same format as :meth:`get_comments`. If the comment is being 
         attached to a node, pass in the node's id (as a string) with the 
         node keyword argument::
 
-            comment = support.add_comment(text, node=node_id)
+            comment = support.add_comment(text, node_id=node_id)
 
         If the comment is the child of another comment, provide the parent's
         id (as a string) with the parent keyword argument::
             
-            comment = support.add_comment(text, parent=parent_id)
+            comment = support.add_comment(text, parent_id=parent_id)
 
         If you would like to store a username with the comment, pass
         in the optional `username` keyword argument::
@@ -274,10 +267,9 @@ class WebSupport(object):
         :param text: the text of the comment.
         :param displayed: for moderation purposes
         :param username: the username of the user making the comment.
-        :param rating: the starting rating of the comment, defaults to 0.
         :param time: the time the comment was created, defaults to now.
         """
-        comment = self.storage.add_comment(text, displayed, username, rating,
+        comment = self.storage.add_comment(text, displayed, username,
                                            time, proposal, node_id, 
                                            parent_id, moderator)
         if not displayed and self.moderation_callback:
@@ -288,10 +280,9 @@ class WebSupport(object):
         """Process a user's vote. The web support package relies
         on the API user to perform authentication. The API user will 
         typically receive a comment_id and value from a form, and then
-        make sure the user is authenticated. A unique integer `user_id` 
-        (usually the User primary key) must be passed in, which will 
-        also be used to retrieve the user's past voting information. 
-        An example, once again in Flask::
+        make sure the user is authenticated. A unique username  must be 
+        passed in, which will also be used to retrieve the user's past 
+        voting data. An example, once again in Flask::
 
             @app.route('/docs/process_vote', methods=['POST'])
             def process_vote():
@@ -301,11 +292,11 @@ class WebSupport(object):
                 value = request.form.get('value')
                 if value is None or comment_id is None:
                     abort(400)
-                support.process_vote(comment_id, g.user.id, value)
+                support.process_vote(comment_id, g.user.name, value)
                 return "success"
 
         :param comment_id: the comment being voted on
-        :param user_id: the unique integer id of the user voting
+        :param username: the unique username of the user voting
         :param value: 1 for an upvote, -1 for a downvote, 0 for an unvote.
         """
         value = int(value)
@@ -329,7 +320,11 @@ class WebSupport(object):
     def accept_comment(self, comment_id, moderator=False):
         """Accept a comment that is pending moderation.
 
+        This raises :class:`~sphinx.websupport.errors.UserNotAuthorizedError`
+        if moderator is False.
+
         :param comment_id: The id of the comment that was accepted.
+        :param moderator: Whether the user making the request is a moderator.
         """
         if not moderator:
             raise UserNotAuthorizedError()
@@ -338,8 +333,60 @@ class WebSupport(object):
     def reject_comment(self, comment_id, moderator=False):
         """Reject a comment that is pending moderation.
 
+        This raises :class:`~sphinx.websupport.errors.UserNotAuthorizedError`
+        if moderator is False.
+
         :param comment_id: The id of the comment that was accepted.
+        :param moderator: Whether the user making the request is a moderator.
         """
         if not moderator:
             raise UserNotAuthorizedError()
         self.storage.reject_comment(comment_id)
+
+    def _make_base_comment_options(self):
+        """Helper method to create the part of the COMMENT_OPTIONS javascript
+        that remains the same throughout the lifetime of the
+        :class:`~sphinx.websupport.WebSupport` object.
+        """
+        parts = ['<script type="text/javascript">', 
+                 'var COMMENT_OPTIONS = {']
+        if self.docroot is not '':
+            parts.append('addCommentURL: "/%s/%s",' % (self.docroot, 
+                                                       'add_comment'))
+            parts.append('getCommentsURL: "/%s/%s",' % (self.docroot, 
+                                                        'get_comments'))
+            parts.append('processVoteURL: "/%s/%s",' % (self.docroot, 
+                                                        'process_vote'))
+            parts.append('acceptCommentURL: "/%s/%s",' % (self.docroot, 
+                                                          'accept_comment'))
+            parts.append('rejectCommentURL: "/%s/%s",' % (self.docroot, 
+                                                          'reject_comment'))
+            parts.append('deleteCommentURL: "/%s/%s",' % (self.docroot, 
+                                                          'delete_comment'))
+
+        if self.staticdir != 'static':
+            p = lambda file: '%s/_static/%s' % (self.staticdir, file)
+            parts.append('commentImage: "/%s",' % p('comment.png') )
+            parts.append('upArrow: "/%s",' % p('up.png'))
+            parts.append('downArrow: "/%s",' % p('down.png'))
+            parts.append('upArrowPressed: "/%s",' % p('up-pressed.png'))
+            parts.append('downArrowPressed: "/%s",' % p('down-pressed.png'))
+
+        self.base_comment_opts = '\n'.join(parts)            
+            
+    def _make_comment_options(self, username, moderator):
+        """Helper method to create the parts of the COMMENT_OPTIONS
+        javascript that are unique to each request.
+
+        :param username: The username of the user making the request.
+        :param moderator: Whether the user making the request is a moderator.
+        """
+        parts = [self.base_comment_opts]
+        if username is not '':
+            parts.append('voting: true,')
+            parts.append('username: "%s",' % username)
+        parts.append('moderator: %s' % str(moderator).lower())
+        parts.append('};')
+        parts.append('</script>')
+        return '\n'.join(parts)            
+
diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index 0e613222e..80f91ab1d 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -20,7 +20,7 @@ class BaseSearch(object):
         is a list of pagenames that will be reindexed. You may want to remove
         these from the search index before indexing begins.
 
-        `param changed` is a list of pagenames that will be re-indexed
+        :param changed: a list of pagenames that will be re-indexed
         """
         pass
 
@@ -37,11 +37,9 @@ class BaseSearch(object):
         won't want to override this unless you need access to the `doctree`. 
         Override :meth:`add_document` instead.
 
-        `pagename` is the name of the page to be indexed
-
-        `title` is the title of the page to be indexed
-
-        `doctree` is the docutils doctree representation of the page
+        :param pagename: the name of the page to be indexed
+        :param title: the title of the page to be indexed
+        :param doctree: is the docutils doctree representation of the page
         """
         self.add_document(pagename, title, doctree.astext())
 
@@ -50,18 +48,16 @@ class BaseSearch(object):
         This method should should do everything necessary to add a single
         document to the search index.
 
-        `pagename` is name of the page being indexed.
-        It is the combination of the source files relative path and filename,
+        `pagename` is name of the page being indexed. It is the combination
+        of the source files relative path and filename,
         minus the extension. For example, if the source file is 
         "ext/builders.rst", the `pagename` would be "ext/builders". This
         will need to be returned with search results when processing a 
         query.
-
-        `title` is the page's title, and will need to be returned with 
-        search results.
-
-        `text` is the full text of the page. You probably want to store this
-        somehow to use while creating the context for search results.
+        
+        :param pagename: the name of the page being indexed
+        :param title: the page's title
+        :param text: the full text of the page
         """
         raise NotImplementedError()
 
@@ -73,7 +69,7 @@ class BaseSearch(object):
         don't want to use the included :meth:`extract_context` method.
         Override :meth:`handle_query` instead.
         
-        `q` is the search query string.
+        :param q: the search query string.
         """
         self.context_re = re.compile('|'.join(q.split()), re.I)
         return self.handle_query(q)
@@ -91,6 +87,8 @@ class BaseSearch(object):
 
         The :meth:`extract_context` method is provided as a simple way
         to create the `context`.
+
+        :param q: the search query
         """
         raise NotImplementedError()
 
@@ -98,9 +96,8 @@ class BaseSearch(object):
         """Extract the context for the search query from the documents
         full `text`.
 
-        `text` is the full text of the document to create the context for.
-
-        `length` is the length of the context snippet to return.
+        :param text: the full text of the document to create the context for
+        :param length: the length of the context snippet to return.
         """
         res = self.context_re.search(text)
         if res is None:
diff --git a/sphinx/websupport/storage/__init__.py b/sphinx/websupport/storage/__init__.py
index 6948c8c73..70b23150d 100644
--- a/sphinx/websupport/storage/__init__.py
+++ b/sphinx/websupport/storage/__init__.py
@@ -16,16 +16,14 @@ class StorageBackend(object):
         """
         pass
 
-    def add_node(self, document, line, source, treeloc):
+    def add_node(self, document, line, source):
         """Add a node to the StorageBackend.
 
-        `document` is the name of the document the node belongs to.
+        :param document: the name of the document the node belongs to.
         
-        `line` is the line in the source where the node begins.
+        :param line: the line in the source where the node begins.
 
-        `source` is the source files name.
-        
-        `treeloc` is for future use.
+        :param source: the source files name.
         """
         raise NotImplementedError()
     
@@ -35,14 +33,77 @@ class StorageBackend(object):
         """
         pass
 
-    def add_comment(self, text, displayed, username, rating, time,
-                    proposal, node, parent):
-        """Called when a comment is being added."""
+    def add_comment(self, text, displayed, username, time,
+                    proposal, node_id, parent_id, moderator):
+        """Called when a comment is being added.
+        
+        :param text: the text of the comment
+        :param displayed: whether the comment should be displayed
+        :param username: the name of the user adding the comment
+        :param time: a date object with the time the comment was added
+        :param proposal: the text of the proposal the user made
+        :param node_id: the id of the node that the comment is being added to
+        :param parent_id: the id of the comment's parent comment.
+        :param moderator: whether the user adding the comment is a moderator
+        """
         raise NotImplementedError()
 
-    def get_data(self, parent_id, user_id, moderator):
-        """Called to retrieve all comments for a node."""
+    def delete_comment(self, comment_id, username, moderator):
+        """Delete a comment.
+
+        Raises :class:`~sphinx.websupport.errors.UserNotAuthorizedError`
+        if moderator is False and `username` doesn't match the username
+        on the comment.
+
+        :param comment_id: The id of the comment being deleted.
+        :param username: The username of the user requesting the deletion.
+        :param moderator: Whether the user is a moderator.
+        """
         raise NotImplementedError()
 
-    def process_vote(self, comment_id, user_id, value):
+    def get_data(self, node_id, username, moderator):
+        """Called to retrieve all data for a node. This should return a
+        dict with two keys, *source* and *comments* as described by
+        :class:`~sphinx.websupport.WebSupport`'s
+        :meth:`~sphinx.websupport.WebSupport.get_data` method.
+
+        :param node_id: The id of the node to get data for.
+        :param username: The name of the user requesting the data.
+        :param moderator: Whether the requestor is a moderator.
+        """
+        raise NotImplementedError()
+
+    def process_vote(self, comment_id, username, value):
+        """Process a vote that is being cast. `value` will be either -1, 0,
+        or 1.
+
+        :param comment_id: The id of the comment being voted on.
+        :param username: The username of the user casting the vote.
+        :param value: The value of the vote being cast.
+        """
+        raise NotImplementedError()
+
+    def update_username(self, old_username, new_username):
+        """If a user is allowed to change their username this method should
+        be called so that there is not stagnate data in the storage system.
+
+        :param old_username: The username being changed.
+        :param new_username: What the username is being changed to.
+        """
+        raise NotImplementedError()
+
+    def accept_comment(self, comment_id):
+        """Called when a moderator accepts a comment. After the method is
+        called the comment should be displayed to all users.
+
+        :param comment_id: The id of the comment being accepted.
+        """
+        raise NotImplementedError()
+
+    def reject_comment(self, comment_id):
+        """Called when a moderator rejects a comment. The comment should
+        then be deleted.
+
+        :param comment_id: The id of the comment being accepted.
+        """
         raise NotImplementedError()
diff --git a/sphinx/websupport/storage/db.py b/sphinx/websupport/storage/db.py
index 12c1e1d5e..983eb66d9 100644
--- a/sphinx/websupport/storage/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -81,11 +81,10 @@ class Node(Base):
         
         return comments
 
-    def __init__(self, document, line, source, treeloc):
+    def __init__(self, document, line, source):
         self.document = document
         self.line = line
         self.source = source
-        self.treeloc = treeloc
 
 class Comment(Base):
     __tablename__ = db_prefix + 'comments'
diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
index 2e182311e..7a906dcba 100644
--- a/sphinx/websupport/storage/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -27,8 +27,8 @@ class SQLAlchemyStorage(StorageBackend):
     def pre_build(self):
         self.build_session = Session()
 
-    def add_node(self, document, line, source, treeloc):
-        node = Node(document, line, source, treeloc)
+    def add_node(self, document, line, source):
+        node = Node(document, line, source)
         self.build_session.add(node)
         self.build_session.flush()
         return node
@@ -37,7 +37,7 @@ class SQLAlchemyStorage(StorageBackend):
         self.build_session.commit()
         self.build_session.close()
 
-    def add_comment(self, text, displayed, username, rating, time,
+    def add_comment(self, text, displayed, username, time,
                     proposal, node_id, parent_id, moderator):
         session = Session()
         
@@ -55,7 +55,7 @@ class SQLAlchemyStorage(StorageBackend):
         else:
             proposal_diff = None
 
-        comment = Comment(text, displayed, username, rating, 
+        comment = Comment(text, displayed, username, 0, 
                           time or datetime.now(), proposal, proposal_diff)
         session.add(comment)
         session.flush()
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 64a431d8e..05bc2c8b3 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -57,6 +57,5 @@ class WebSupportTranslator(HTMLTranslator):
         storage = self.builder.app.storage
         db_node_id = storage.add_node(document=self.builder.cur_docname,
                                       line=node.line,
-                                      source=node.rawsource or node.astext(),
-                                      treeloc='???')
+                                      source=node.rawsource or node.astext())
         return db_node_id

From 71a14cdd34393c11ecc04c43859e6f5b36295b21 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 14:36:19 -0500
Subject: [PATCH 091/127] updated CHANGES.jacobmason

---
 CHANGES.jacobmason | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/CHANGES.jacobmason b/CHANGES.jacobmason
index bd87c71c6..c445006c2 100644
--- a/CHANGES.jacobmason
+++ b/CHANGES.jacobmason
@@ -12,4 +12,16 @@ June 21 - June 26: Implement server side search with two search adapters,
 one for Xapian and one for Whoosh
 
 June 28 - July 12: Implement voting system on the backend, and created a
-jQuery script to handle voting on the frontend.
\ No newline at end of file
+jQuery script to handle voting on the frontend.
+
+July 13 - July 19: Added documentation for the web support package.
+
+July 20 - July 27: Added a system to allow user's to propose changes to
+documentation along with comments.
+
+July 28 - August 3: Added tests for the web support package. Refactored
+sqlalchemy storage to be more efficient.
+
+August 4 - August 7: Added comment moderation system. Added more 
+documentation. General code cleanup.
+

From c5e43ca3c9aefa6191b862b17ed1a4136a0b12f3 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 14:43:32 -0500
Subject: [PATCH 092/127] create a searcher for each query

---
 sphinx/websupport/search/whooshsearch.py | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/sphinx/websupport/search/whooshsearch.py b/sphinx/websupport/search/whooshsearch.py
index 257393a6a..0f4635314 100644
--- a/sphinx/websupport/search/whooshsearch.py
+++ b/sphinx/websupport/search/whooshsearch.py
@@ -31,7 +31,6 @@ class WhooshSearch(BaseSearch):
             self.index = index.open_dir(db_path)
         else:
             self.index = index.create_in(db_path, schema=self.schema)
-        self.searcher = self.index.searcher()
 
     def init_indexing(self, changed=[]):
         for changed_path in changed:
@@ -40,8 +39,6 @@ class WhooshSearch(BaseSearch):
 
     def finish_indexing(self):
         self.index_writer.commit()
-        # Create a new searcher so changes can be seen immediately
-        self.searcher = self.index.searcher()
 
     def add_document(self, pagename, title, text):
         self.index_writer.add_document(path=unicode(pagename),
@@ -49,7 +46,8 @@ class WhooshSearch(BaseSearch):
                                        text=text)
 
     def handle_query(self, q):
-        whoosh_results = self.searcher.find('text', q)
+        searcher = self.index.searcher()
+        whoosh_results = searcher.find('text', q)
         results = []
         for result in whoosh_results:
             context = self.extract_context(result['text'])

From 3f29ff6204501bc9ff3f1c763c5c90148bd333ca Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 14:47:18 -0500
Subject: [PATCH 093/127] moved NullSearchException to sphinx.websupport.errors

---
 sphinx/websupport/errors.py            | 7 ++++++-
 sphinx/websupport/search/nullsearch.py | 7 ++++---
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/sphinx/websupport/errors.py b/sphinx/websupport/errors.py
index e78abc217..53106dfb8 100644
--- a/sphinx/websupport/errors.py
+++ b/sphinx/websupport/errors.py
@@ -10,7 +10,8 @@
 """
 
 __all__ = ['DocumentNotFoundError', 'SrcdirNotSpecifiedError',
-           'UserNotAuthorizedError', 'CommentNotAllowedError']
+           'UserNotAuthorizedError', 'CommentNotAllowedError',
+           'NullSearchException']
 
 class DocumentNotFoundError(Exception):
     pass
@@ -26,3 +27,7 @@ class UserNotAuthorizedError(Exception):
 
 class CommentNotAllowedError(Exception):
     pass
+
+
+class NullSearchException(Exception):
+    pass
diff --git a/sphinx/websupport/search/nullsearch.py b/sphinx/websupport/search/nullsearch.py
index ad3d7daef..743983c48 100644
--- a/sphinx/websupport/search/nullsearch.py
+++ b/sphinx/websupport/search/nullsearch.py
@@ -10,11 +10,12 @@
 """
 
 from sphinx.websupport.search import BaseSearch
-
-class NullSearchException(Exception):
-    pass
+from sphinx.websupport.errors import *
 
 class NullSearch(BaseSearch):
+    """A search adapter that does nothing. Used when no search adapter
+    is specified.
+    """
     def feed(self, pagename, title, doctree):
         pass
 

From 3b3e001eb970846e4711e9a0b93d2296c6a2e29b Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 15:22:52 -0500
Subject: [PATCH 094/127] added more comments/docstrings

---
 sphinx/websupport/storage/db.py               | 31 +++++++-
 sphinx/websupport/storage/differ.py           | 73 +++++++++++--------
 .../websupport/storage/sqlalchemystorage.py   | 16 ++--
 3 files changed, 80 insertions(+), 40 deletions(-)

diff --git a/sphinx/websupport/storage/db.py b/sphinx/websupport/storage/db.py
index 983eb66d9..64f7f3e25 100644
--- a/sphinx/websupport/storage/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -34,6 +34,12 @@ class Node(Base):
     source = Column(Text, nullable=False)
 
     def nested_comments(self, username, moderator):
+        """Create a tree of comments. First get all comments that are
+        descendents of this node, then convert them to a tree form.
+
+        :param username: the name of the user to get comments for.
+        :param moderator: whether the user is moderator.
+        """
         session = Session()
 
         if username:
@@ -45,24 +51,30 @@ class Node(Base):
             cvalias = aliased(CommentVote, sq)
             q = session.query(Comment, cvalias.value).outerjoin(cvalias)
         else:
+            # If a username is not provided, we don't need to join with
+            # CommentVote.
             q = session.query(Comment)
 
         # Filter out all comments not descending from this node.
         q = q.filter(Comment.path.like(str(self.id) + '.%'))
-        # Filter out non-displayed comments if this isn't a moderator.
+
         if not moderator:
             q = q.filter(Comment.displayed == True)
+
         # Retrieve all results. Results must be ordered by Comment.path
         # so that we can easily transform them from a flat list to a tree.
         results = q.order_by(Comment.path).all()
         session.close()
 
-        # We now need to convert the flat list of results to a nested
-        # lists to form the comment tree. Results will by ordered by
-        # the materialized path.
         return self._nest_comments(results, username)
 
     def _nest_comments(self, results, username):
+        """Given the flat list of results, convert the list into a
+        tree.
+
+        :param results: the flat list of comments
+        :param username: the name of the user requesting the comments.
+        """
         comments = []
         list_stack = [comments]
         for r in results:
@@ -87,6 +99,7 @@ class Node(Base):
         self.source = source
 
 class Comment(Base):
+    """An individual Comment being stored."""
     __tablename__ = db_prefix + 'comments'
 
     id = Column(Integer, primary_key=True)
@@ -110,6 +123,9 @@ class Comment(Base):
         self.proposal_diff = proposal_diff
 
     def set_path(self, node_id, parent_id):
+        """Set the materialized path for this comment."""
+        # This exists because the path can't be set until the session has
+        # been flushed and this Comment has an id.
         if node_id:
             self.path = '%s.%s' % (node_id, self.id)
         else:
@@ -120,6 +136,9 @@ class Comment(Base):
             self.path = '%s.%s' %  (parent_path, self.id)
 
     def serializable(self, vote=0):
+        """Creates a serializable representation of the comment. This is
+        converted to JSON, and used on the client side.
+        """
         delta = datetime.now() - self.time
 
         time = {'year': self.time.year,
@@ -149,6 +168,9 @@ class Comment(Base):
                 'children': []}
 
     def pretty_delta(self, delta):
+        """Create a pretty representation of the Comment's age.
+        (e.g. 2 minutes).
+        """
         days = delta.days
         seconds = delta.seconds
         hours = seconds / 3600
@@ -162,6 +184,7 @@ class Comment(Base):
         return '%s %s ago' % dt if dt[0] == 1 else '%s %ss ago' % dt
 
 class CommentVote(Base):
+    """A vote a user has made on a Comment."""
     __tablename__ = db_prefix + 'commentvote'
 
     username = Column(String(64), primary_key=True)
diff --git a/sphinx/websupport/storage/differ.py b/sphinx/websupport/storage/differ.py
index c82ba7427..068d7e6fc 100644
--- a/sphinx/websupport/storage/differ.py
+++ b/sphinx/websupport/storage/differ.py
@@ -14,39 +14,18 @@ from cgi import escape
 from difflib import Differ
 
 class CombinedHtmlDiff(object):
-
+    """Create an HTML representation of the differences between two pieces
+    of text.
+    """
     highlight_regex = re.compile(r'([\+\-\^]+)')
 
-    def _highlight_text(self, text, next, tag):
-        next = next[2:]
-        new_text = []
-        start = 0
-        for match in self.highlight_regex.finditer(next):
-            new_text.append(text[start:match.start()])
-            new_text.append('<%s>' % tag)
-            new_text.append(text[match.start():match.end()])
-            new_text.append('</%s>' % tag)
-            start = match.end()
-        new_text.append(text[start:])
-        return ''.join(new_text)
-
-    def _handle_line(self, line, next=None):
-        prefix = line[0]
-        text = line[2:]
-
-        if prefix == ' ':
-            return text
-        elif prefix == '?':
-            return ''
-        
-        if next is not None and next[0] == '?':
-            tag = 'ins' if prefix == '+' else 'del'
-            text = self._highlight_text(text, next, tag)
-        css_class = 'prop_added' if prefix == '+' else 'prop_removed'
-        
-        return '<span class="%s">%s</span>\n' % (css_class, text.rstrip())
-
     def make_html(self, source, proposal):
+        """Return the HTML representation of the differences between
+        `source` and `proposal`.
+
+        :param source: the original text
+        :param proposal: the proposed text
+        """
         proposal = escape(proposal)
 
         differ = Differ()
@@ -64,3 +43,37 @@ class CombinedHtmlDiff(object):
                 self._handle_line(line)
                 break
         return ''.join(html)
+
+    def _handle_line(self, line, next=None):
+        """Handle an individual line in a diff."""
+        prefix = line[0]
+        text = line[2:]
+
+        if prefix == ' ':
+            return text
+        elif prefix == '?':
+            return ''
+        
+        if next is not None and next[0] == '?':
+            tag = 'ins' if prefix == '+' else 'del'
+            text = self._highlight_text(text, next, tag)
+        css_class = 'prop_added' if prefix == '+' else 'prop_removed'
+        
+        return '<span class="%s">%s</span>\n' % (css_class, text.rstrip())
+
+    def _highlight_text(self, text, next, tag):
+        """Highlight the specific changes made to a line by adding
+        <ins> and <del> tags.
+        """
+        next = next[2:]
+        new_text = []
+        start = 0
+        for match in self.highlight_regex.finditer(next):
+            new_text.append(text[start:match.start()])
+            new_text.append('<%s>' % tag)
+            new_text.append(text[match.start():match.end()])
+            new_text.append('</%s>' % tag)
+            start = match.end()
+        new_text.append(text[start:])
+        return ''.join(new_text)
+
diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
index 7a906dcba..553450d32 100644
--- a/sphinx/websupport/storage/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -18,6 +18,9 @@ from sphinx.websupport.storage.db import Base, Node, Comment, CommentVote,\
 from sphinx.websupport.storage.differ import CombinedHtmlDiff
 
 class SQLAlchemyStorage(StorageBackend):
+    """A :class:`~sphinx.websupport.storage.StorageBackend` using 
+    SQLAlchemy.
+    """
     def __init__(self, engine):
         self.engine = engine
         Base.metadata.bind = engine
@@ -40,7 +43,8 @@ class SQLAlchemyStorage(StorageBackend):
     def add_comment(self, text, displayed, username, time,
                     proposal, node_id, parent_id, moderator):
         session = Session()
-        
+        proposal_diff = None
+
         if node_id and proposal:
             node = session.query(Node).filter(Node.id == node_id).one()
             differ = CombinedHtmlDiff()
@@ -51,19 +55,18 @@ class SQLAlchemyStorage(StorageBackend):
             if not parent.displayed:
                 raise CommentNotAllowedError(
                     "Can't add child to a parent that is not displayed")
-            proposal_diff = None
-        else:
-            proposal_diff = None
 
         comment = Comment(text, displayed, username, 0, 
                           time or datetime.now(), proposal, proposal_diff)
         session.add(comment)
         session.flush()
+        # We have to flush the session before setting the path so the
+        # Comment has an id.
         comment.set_path(node_id, parent_id)
         session.commit()
-        comment = comment.serializable()
+        d = comment.serializable()
         session.close()
-        return comment
+        return d
 
     def delete_comment(self, comment_id, username, moderator):
         session = Session()
@@ -72,6 +75,7 @@ class SQLAlchemyStorage(StorageBackend):
         if moderator or comment.username == username:
             comment.username = '[deleted]'
             comment.text = '[deleted]'
+            comment.proposal = ''
             session.commit()
             session.close()
         else:

From e599abe386ed4a548be1c5f8d6a89014c78d368b Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 15:46:54 -0500
Subject: [PATCH 095/127] A few changes to sqlalchemystorage

---
 .../websupport/storage/sqlalchemystorage.py   | 26 +++++++++++++------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
index 553450d32..94318a965 100644
--- a/sphinx/websupport/storage/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -11,6 +11,8 @@
 
 from datetime import datetime
 
+from sqlalchemy.orm import aliased
+
 from sphinx.websupport.errors import *
 from sphinx.websupport.storage import StorageBackend
 from sphinx.websupport.storage.db import Base, Node, Comment, CommentVote,\
@@ -92,12 +94,13 @@ class SQLAlchemyStorage(StorageBackend):
 
     def process_vote(self, comment_id, username, value):
         session = Session()
-        vote = session.query(CommentVote).filter(
-            CommentVote.comment_id == comment_id).filter(
-            CommentVote.username == username).first()
 
-        comment = session.query(Comment).filter(
-            Comment.id == comment_id).first()
+        subquery = session.query(CommentVote).filter(
+            CommentVote.username == username).subquery()
+        vote_alias = aliased(CommentVote, subquery)
+        q = session.query(Comment, vote_alias).outerjoin(vote_alias).filter(
+            Comment.id == comment_id)
+        comment, vote = q.one()
 
         if vote is None:
             vote = CommentVote(comment_id, username, value)
@@ -105,32 +108,39 @@ class SQLAlchemyStorage(StorageBackend):
         else:
             comment.rating += value - vote.value
             vote.value = value
+
         session.add(vote)
         session.commit()
         session.close()
 
     def update_username(self, old_username, new_username):
         session = Session()
+
         session.query(Comment).filter(Comment.username == old_username).\
             update({Comment.username: new_username})
         session.query(CommentVote).\
             filter(CommentVote.username == old_username).\
             update({CommentVote.username: new_username})
+
         session.commit()
         session.close()
 
     def accept_comment(self, comment_id):
         session = Session()
-        comment = session.query(Comment).\
-            filter(Comment.id == comment_id).one()
-        comment.displayed = True
+
+        comment = session.query(Comment).filter(
+            Comment.id == comment_id).update(
+            {Comment.displayed: True})
+
         session.commit()
         session.close()
 
     def reject_comment(self, comment_id):
         session = Session()
+
         comment = session.query(Comment).\
             filter(Comment.id == comment_id).one()
         session.delete(comment)
+
         session.commit()
         session.close()

From 861289ad8e794919b8d2997199a7d08e6c5755eb Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 16:47:29 -0500
Subject: [PATCH 096/127] hide proposal textarea after a comment is added

---
 sphinx/themes/basic/static/websupport.js | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index aeef3ece1..62912d6b8 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -212,18 +212,22 @@
   function addComment(form) {
     // Disable the form that is being submitted.
     form.find('textarea,input').attr('disabled', 'disabled');
+    var node_id = form.find('input[name="node"]').val();
 
     // Send the comment to the server.
     $.ajax({
       type: "POST",
       url: opts.addCommentURL,
       dataType: 'json',
-      data: {node: form.find('input[name="node"]').val(),
+      data: {node: node_id,
              parent: form.find('input[name="parent"]').val(),
 	     text: form.find('textarea[name="comment"]').val(),
 	     proposal: form.find('textarea[name="proposal"]').val()},
       success: function(data, textStatus, error) {
 	// Reset the form.
+	if (node_id) {
+	  hideProposeChange(node_id);
+	}
 	form.find('textarea')
 	  .val('')
 	    .add(form.find('input'))
@@ -378,7 +382,7 @@
     $('a.hide_propose_change').hide();
     $('a.show_propose_change').show();
     var textarea = $('textarea[name="proposal"]');
-    textarea.val('');
+    textarea.val('').removeAttr('disabled');
     textarea.slideUp('fast');
   };
 

From 18ef86f0452595e0d7a414ceddfc9615ca476549 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 16:53:29 -0500
Subject: [PATCH 097/127] fixed comment reply width

---
 sphinx/themes/basic/static/websupport.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 62912d6b8..c4fa57555 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -630,7 +630,7 @@
   var replyTemplate = '    <li>\
       <div class="reply_div" id="rd<%id%>">\
 	<form id="rf<%id%>">\
-	  <textarea name="comment"></textarea>\
+	  <textarea name="comment" cols="80"></textarea>\
           <input type="submit" value="add reply" />\
           <input type="hidden" name="parent" value="<%id%>" />\
           <input type="hidden" name="node" value="" />\

From 0f98c779c0813ffe3413f8678bb7c8cd88aabdab Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 18:31:13 -0500
Subject: [PATCH 098/127] added get_metadata

---
 sphinx/websupport/__init__.py                  | 15 ++++++++++++++-
 sphinx/websupport/storage/__init__.py          |  9 +++++++++
 sphinx/websupport/storage/db.py                |  5 +++++
 sphinx/websupport/storage/sqlalchemystorage.py | 14 ++++++++++++++
 4 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 38ebd2340..090fee1ad 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -160,7 +160,11 @@ class WebSupport(object):
 
         document = pickle.load(f)
         comment_opts = self._make_comment_options(username, moderator)
-        document['js'] = comment_opts + '\n' + document['js']
+        comment_metadata = self.storage.get_metadata(docname, moderator)
+                                                             
+        document['js'] = '\n'.join([comment_opts,
+                                    self._make_metadata(comment_metadata),
+                                    document['js']])
         return document
 
     def get_search_results(self, q):
@@ -390,3 +394,12 @@ class WebSupport(object):
         parts.append('</script>')
         return '\n'.join(parts)            
 
+    def _make_metadata(self, data):
+        node_js = ', '.join(['%s: %s' % (node_id, comment_count) 
+                             for node_id, comment_count in data.iteritems()])
+        js = """
+<script type="text/javascript">
+  var COMMENT_METADATA = {%s};
+</script>""" % node_js
+        return js
+
diff --git a/sphinx/websupport/storage/__init__.py b/sphinx/websupport/storage/__init__.py
index 70b23150d..24d4ade55 100644
--- a/sphinx/websupport/storage/__init__.py
+++ b/sphinx/websupport/storage/__init__.py
@@ -61,6 +61,15 @@ class StorageBackend(object):
         """
         raise NotImplementedError()
 
+    def get_metadata(self, docname, moderator):
+        """Get metadata for a document. This is currently just a dict
+        of node_id's with associated comment counts.
+
+        :param docname: the name of the document to get metadata for.
+        :param moderator: whether the requester is a moderator.
+        """
+        raise NotImplementedError()
+
     def get_data(self, node_id, username, moderator):
         """Called to retrieve all data for a node. This should return a
         dict with two keys, *source* and *comments* as described by
diff --git a/sphinx/websupport/storage/db.py b/sphinx/websupport/storage/db.py
index 64f7f3e25..4a84cd086 100644
--- a/sphinx/websupport/storage/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -112,6 +112,9 @@ class Comment(Base):
     proposal_diff = Column(Text)
     path = Column(String(256), index=True)
 
+    node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
+    node = relation(Node, backref="comments")
+
     def __init__(self, text, displayed, username, rating, time, 
                  proposal, proposal_diff):
         self.text = text
@@ -127,12 +130,14 @@ class Comment(Base):
         # This exists because the path can't be set until the session has
         # been flushed and this Comment has an id.
         if node_id:
+            self.node_id = node_id
             self.path = '%s.%s' % (node_id, self.id)
         else:
             session = Session()
             parent_path = session.query(Comment.path).\
                 filter(Comment.id == parent_id).one().path
             session.close()
+            self.node_id = parent_path.split('.')[0]
             self.path = '%s.%s' %  (parent_path, self.id)
 
     def serializable(self, vote=0):
diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
index 94318a965..1aaa84738 100644
--- a/sphinx/websupport/storage/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -12,6 +12,7 @@
 from datetime import datetime
 
 from sqlalchemy.orm import aliased
+from sqlalchemy.sql import func
 
 from sphinx.websupport.errors import *
 from sphinx.websupport.storage import StorageBackend
@@ -84,6 +85,19 @@ class SQLAlchemyStorage(StorageBackend):
             session.close()
             raise UserNotAuthorizedError()
 
+    def get_metadata(self, docname, moderator):
+        session = Session()
+        subquery = session.query(
+            Comment.id, Comment.node_id, 
+            func.count('*').label('comment_count')).group_by(
+            Comment.node_id).subquery()
+        nodes = session.query(Node.id, subquery.c.comment_count).outerjoin(
+            (subquery, Node.id==subquery.c.node_id)).filter(
+            Node.document==docname)
+        session.close()
+        session.commit()
+        return dict([(k, v or 0) for k, v in nodes])
+
     def get_data(self, node_id, username, moderator):
         session = Session()
         node = session.query(Node).filter(Node.id == node_id).one()

From d77cbf3043b88a31424d44538b8b8bb5fdc1e490 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Mon, 9 Aug 2010 19:07:18 -0500
Subject: [PATCH 099/127] added comment metadata to frontend

---
 sphinx/themes/basic/static/comment-bright.png | Bin 0 -> 3500 bytes
 sphinx/themes/basic/static/websupport.js      |   8 +++++++-
 sphinx/websupport/__init__.py                 |   2 ++
 3 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 sphinx/themes/basic/static/comment-bright.png

diff --git a/sphinx/themes/basic/static/comment-bright.png b/sphinx/themes/basic/static/comment-bright.png
new file mode 100644
index 0000000000000000000000000000000000000000..551517b8c83b76f734ff791f847829a760ad1903
GIT binary patch
literal 3500
zcmV;d4O8-oP)<h;3K|Lk000e1NJLTq000mG000mO1^@s6AM^iV000V4X+uL$P-t&-
zZ*ypGa3D!TLm+T+Z)Rz1WdHzp+MQEpR8#2|J@?-9LQ9B%luK_?6$l_wLW_VDktQl3
z2@pz%A)(n7QNa;KMFbnjpojyGj)066Q7jCK3fKqaA)=0hqlk*i`{8?|Yu3E?=FR@K
z*FNX0^PRKL2fzpnmPj*EHGmAMLLL#|gU7_i;p8qrfeIvW01ybXWFd3?BLM*Temp!Y
zBESc}00DT@3kU$fO`E_l9Ebl8>Oz@Z0f2-7z;ux~O9+4z06=<<LZ$#fMgf4Gm?l#I
zpacM5%VT2W08lLeU?+d((*S^-_?deF09%wH6#<};03Z`(h(rKrI{>WDR*FRcSTFz-
zW=q650N5=6FiBTtNC2?60Km==3$g$R3;-}uh=nNt1bYBr$Ri_o0EC$U6h`t_Jn<{8
z5a%iY0C<_QJh>z}MS)ugEpZ1|S1ukX&Pf+56gFW3VVXcL!g-k)GJ!M?;PcD?0HBc-
z5#WRK{dmp}uFlRjj<yb8E$Y7p{~}^y<NoE(t8hR70O53g(f%wivl@Uq27qn;q9yJG
zXkH7Tb@z*AvJXJD0HEpGSMzZAemp!yp^&-R+2!Qq*h<7gTVcvqeg0>{U%*%WZ25jX
z{P*?XzTzZ-GF^d31o+^>%=Ap99M6&ogks$0k4OBs3;+Bb(;~!4V!2o<6ys46agIcq
zjPo+3B8fthDa9qy|77CdEc*jK-!%ZRYCZvbku9iQV*~a}ClFY4z~c7+0P?$U!PF=S
z1Au6Q;m>#f??3%Vpd|o+W=WE9003S@Bra6Svp>fO002awfhw>;8}z{#EWidF!3EsG
z3;bX<ghC|5!a@*23S@vBa$qT}f<h>U&9EIRU@z1_9W=mEXoiz;4lcq~xDGvV5BgyU
zp1~-*fe8db$Osc*A=-!mVv1NJjtCc-h4>-CNCXm#Bp}I%6j35eku^v$Qi@a{RY)E3
zJ#qp$hg?Rwkvqr$GJ^buyhkyVfwECO)C{#lxu`c9ghrwZ&}4KmnvWKso6vH!8a<3Q
zq36)6Xb;+tK10Vaz~~qUGsJ8#F2=(`u{bOVlVi)VBCHIn#u~6ztOL7=^<&SmcLWlF
zMZgI*1b0FpVIDz9SWH+>*hr`#93(Um+6gxa1B6k+CnA%mOSC4s5&6UzVlpv@SV$}*
z))J2sFA#f(L&P^E5{W}HC%KRUNwK6<(h|}}(r!{C=`5+6G)NjFlgZj-YqAG9lq?`C
z$c5yc<iq4M<QwE6@>>d>VnA`E_*3F2Qp##d8RZb=H01_mm@+|Cqnc9PsG(F5HIG_C
zt)aG3uTh7n6Et<2In9F>NlT@zqLtGcXcuVrX|L#Xx)I%#9!{6gSJKPrN9dR61N3(c
z4Tcqi$B1Vr8Jidf7-t!G7_XR2rWw<V8OKyGH!<s&=a~<gZ&g?-wkmuTk;)2{N|h#+
z8!9hUsj8-`-l_{#^Hs}KkEvc$eXd4TGgITK3DlOWRjQp(>r)$3XQ?}=hpK0&Z&W{|
zep&sA23f;Q!%st`QJ}G3<GjWo3u76xcq}1n4XcKAfi=V?vCY|hb}GA={T;iDJ*ugp
zIYTo_Ggq@x^OR;k2jiG=_?&c33Fj!Mm-Bv#-W2aC;wc-ZG)%cMWn62jmY0@Tt4OO+
zt4Hg-Hm>cbou<7-yIK2z4nfCCCtN2-XOGSWo##{8Q{ATurxr~;I`ytDs%xbip}RzP
zziy}Qn4Z2~fSycmr`~zJ=lUFdFa1>gZThG6M+{g7vkW8#+YHVaJjFF}Z#*3@$J_By
zLtVo_L#1JrVVB{Ak-5=4qt!-@Mh}c>#$4kh<88)m#-k<%CLtzEP3leVno>=<rYWX7
zOgl`+&CJcB&DNPUn>{htGUuD;o7bD)w_sX$S}eAxwzy?UvgBH(S?;#HZiQMoS*2K2
zT3xe7t(~nU*1N5{rxB;QPLocnp4Ml>u<^FZwyC!nu;thW+pe~4wtZn|Vi#w(#jeBd
zlf9FDx_yoPJqHbk*$%56S{;6Kv~m<WRyy9A&YbQ)eZ};a=`Uwk&k)bpGvl@s%PGWZ
zol~3BM`ssjxpRZ_h>M9!g3B(KJ}#RZ#@)!h<Vtk)ab4kh()FF2vzx;0sN1jZHtuQe
zhuojcG@mJ+Su=Cc!^lJ6QRUG;3!jxRYu~JXPeV_EXSL@eFJmu}SFP8ux21Qg_hIiB
zKK4FxpW{B`JU8Al-dSJFH^8^Zx64n%Z=PR;-$Q>R|78Dq|Iq-afF%KE1Brn_fm;Im
z_<DRHzm7jT+hz8$+3i7$pt(U6L63s1g5|-jA!x|#kgXy2=a|ls&S?&XP=4sv&<A1W
zVT;3l3@3$$g;$0@j&O)r8qqPAHFwe6Lv!Cm`b3sQ-kWDJPdTqGN;N7zsxE3g+Bdp1
zx<AG)W?9VDSe;l&Y)c$DE-J1zZfw5a{O$9H;+^6P<9ipFFUVbRd7;k2^o6GusV)*M
zI+j38h)y_^@IeqNs1}SR@)LI@jtY6g9l~cKFVQy9h}c71DjrVqNGeTwlI)SZHF+e(
zGo>u$xr8UFki1L{Ox>G0o)(&RAZ;=|I=wN2l97;cLaHH6leTB-XXa*h%dBOEvi`+x
zi?=Txl?TadvyiL>SuF~-LZ;|cS}4~l2eM~nS7yJ>iOM;atDY;(?aZ^v+mJV$@1Ote
z62cPUlD4IWOIIx&SmwQ~YB{nzae3Pc;}r!fhE@iwJh+OsDs9zItL;~pu715HdQEGA
zUct(O!L<Qv>kCy1<%NCg+}G`0PgpNm-?d@-hMgNe6^V+j6x$b<6@S<$+<4_1hi}Ti
zncS4LsjI}fWY1>OX6feMEuLErma3QLmkw?X+1j)X-&VBk_4Y;EFPF_I+q;9dL%E~B
zJh;4Nr^(LEJ3myURP<E(R5tF?-L+xY_-@he8+*L=H0;&eTfF!EKFPk@RRL8^)n?UY
z`$_w=_dl+Qs_FQa`)ysVPHl1R#{<#>{Rblsw%57T)g973R8o)DE9*xN#~;4_o$q%o
z4K@u`jhx2fBXC4{<mvYb-}fF3I@)%Od#vFH(;s#nXB{tULYnfLMw?Tb`&(jLx=+kL
z(bnqTdi+P*9}k=~JXv{4^Hj-c+UbJRlV|eJjGdL8eSR+a++f?HwtMGe&fjVeZ|}Mg
zbm7uP|BL54ygSZZ^0;*JvfJeoSGZT2uR33C>U8Qn{*%*B$Ge=nny$HAYq{=vy|sI0
z_vss+H_qMky?OB#|JK!>IX&II^LlUh#rO5!7TtbwC;iULyV-Xq?ybB}ykGP{?LpZ?
z-G|jbTmIbG@7#ZCz;~eY(cDM(28Dyq{*m>M4?_iynUBkc4TkHUI6gT!;y-fz>HMcd
z&t%Ugo)`Y2{>!cx7B7DI)$7;J(U{Spm-3gBzioV_{p!H$8L!*M!p0uH$#^p{Ui4P`
z?ZJ24cOCDe-w#jZd?0@)|7iKK^;6KN`;!@ylm7$*nDhK&GcDTy000JJOGiWi{{a60
z|De66lK=n!32;bRa{vGf6951U69E94oEQKA00(qQO+^RV2niQ93PPz|JOBU!-bqA3
zR5;6pl1pe^WfX<Kz5jFWy@@exLEFUIU=wPB&uCjMh(#zyMT!)`VL_Y}A)sPOtDxY>
zkSdl!omi0~*ntl;2q{jA^;J@WT8O!=A(Gck8fa>hn{#u{`Ty<UmZ;$48*SK&#a@do
zTxVzB&kXn91MHApZ+y|w(yUuEv9>g)!KXI6l>4dj==iVKK6+%4zaRizy(5eryC3d2
z+5Y_D$4}k5v2=Siw{=O)SWY2HJwR3xX1*M*9G^XQ*TCNXF$Vj(kbMJXK0DaS_Sa^1
z?CEa!cFWDhcwxy%a?i@DN|G6-M#uuWU>lss@I>;$xmQ|`u3f;MQ|<i+pZFzHDa=;|
z5kbrooMO2V416$4J>pYuHxxvMeq4TW;>|7Z2*AsqT=`-1O~nTm6O&pNEK?^cf9CX=
zkq5|qAoE7<gSlXrhR#lIk9r2?Ha9f5_RCesJZPj+QjqAngNL9-76eTdm0)Hf-qX^#
zt+gfcDw~#4X?AfC7ds+_xacq^Xn+ub1&{bp&zq_g3|6vGQel0Rq`s777Og8PQ4EEm
z;v$G0bpwMeQ#1ky7!XWxYTk0mqQ&3+LheIVB)Tz<4W}Y;<cNz7mAU~dz8=MasVArz
z7Oq~c)n;}2;^@@))ar~YI7FQ|=d2Jzp%DsAP-+UqO^!GgM4hRsxme`Vbn^Yk>un3V
z^yy=@%6zqN^x`#qW+;e7j>th{6GV}sf*}g7{(R#T)yg-AZh0C&U;WA`AL$qz8()5^
zGFi2`g&L7!c?x+A2oOaG0c*Bg&YZt8cJ{jq_W{uTdA-<;`@iP$$=$H?gYIYc_q^*$
z#k(Key`d40R3?+GmgK8hHJcwiQ~r4By@w9*PuzR>x3#(F?YW_W5pPc(t(@-Y{psOt
zz2!UE_5S)bLF)<rmD^sL?0WXY#py@is+^|tc+=mv&+)&s9XQ{z^}x9<ibo0nY&!9u
a`ab|E?o=hKA+1LM0000<MNUMnLSTYql%5L!

literal 0
HcmV?d00001

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index c4fa57555..99d1a2217 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -617,9 +617,14 @@
    */
   $.fn.comment = function() {
     return this.each(function() {
+      var id = $(this).attr('id').substring(1);
+      var count = COMMENT_METADATA[id]
+      var title = count + ' comment' + (count == 1 ? '' : 's');
+      var image = count > 0 ? opts.commentBrightImage : opts.commentImage;
       $(this).append(
 	$('<a href="#" class="sphinx_comment"></a>')
-	  .html('<img src="' + opts.commentImage + '" alt="comment" />')
+	  .html('<img src="' + image + '" alt="comment" />')
+	  .attr('title', title)
 	  .click(function(event) {
 	    event.preventDefault();
 	    show($(this).parent().attr('id'));
@@ -727,6 +732,7 @@
     rejectCommentURL: '/reject_comment',
     rejectCommentURL: '/delete_comment',
     commentImage: '/static/_static/comment.png',
+    commentBrightImage: '/static/_static/comment-bright.png',
     upArrow: '/static/_static/up.png',
     downArrow: '/static/_static/down.png',
     upArrowPressed: '/static/_static/up-pressed.png',
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 090fee1ad..76715d14a 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -371,6 +371,8 @@ class WebSupport(object):
         if self.staticdir != 'static':
             p = lambda file: '%s/_static/%s' % (self.staticdir, file)
             parts.append('commentImage: "/%s",' % p('comment.png') )
+            parts.append(
+                'commentBrightImage: "/%s",' % p('comment-bright.png') )
             parts.append('upArrow: "/%s",' % p('up.png'))
             parts.append('downArrow: "/%s",' % p('down.png'))
             parts.append('upArrowPressed: "/%s",' % p('up-pressed.png'))

From 023f342bede78031ff498844033662318af9286d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Tue, 10 Aug 2010 17:11:11 +0200
Subject: [PATCH 100/127] Removed trailing whitespace

---
 doc/web/api.rst                               |  69 ++++++------
 doc/web/quickstart.rst                        | 104 +++++++++---------
 doc/web/searchadapters.rst                    |  21 ++--
 doc/web/storagebackends.rst                   |  10 +-
 doc/websupport.rst                            |  10 +-
 sphinx/builders/websupport.py                 |   5 +-
 sphinx/websupport/__init__.py                 |  73 ++++++------
 sphinx/websupport/search/__init__.py          |  13 +--
 sphinx/websupport/search/xapiansearch.py      |   2 +-
 sphinx/websupport/storage/__init__.py         |   6 +-
 sphinx/websupport/storage/db.py               |   6 +-
 sphinx/websupport/storage/differ.py           |   5 +-
 .../websupport/storage/sqlalchemystorage.py   |   6 +-
 tests/test_searchadapters.py                  |   3 +-
 tests/test_websupport.py                      |  28 ++---
 15 files changed, 177 insertions(+), 184 deletions(-)

diff --git a/doc/web/api.rst b/doc/web/api.rst
index b2b7ef952..b63e68643 100644
--- a/doc/web/api.rst
+++ b/doc/web/api.rst
@@ -7,49 +7,49 @@ The WebSupport Class
 
 .. class:: WebSupport
 
-   The main API class for the web support package. All interactions
-   with the web support package should occur through this class.
+    The main API class for the web support package. All interactions
+    with the web support package should occur through this class.
 
-   The class takes the following keyword arguments:
+    The class takes the following keyword arguments:
 
-   srcdir
-       The directory containing reStructuredText source files.
+    srcdir
+        The directory containing reStructuredText source files.
 
-   builddir
-       The directory that build data and static files should be placed in.
-       This should be used when creating a :class:`WebSupport` object that
-       will be used to build data.
+    builddir
+        The directory that build data and static files should be placed in.
+        This should be used when creating a :class:`WebSupport` object that
+        will be used to build data.
 
-   datadir:
-       The directory that the web support data is in. This should be used
-       when creating a :class:`WebSupport` object that will be used to
-       retrieve data.
+    datadir:
+        The directory that the web support data is in. This should be used
+        when creating a :class:`WebSupport` object that will be used to
+        retrieve data.
 
-   search:
-       This may contain either a string (e.g. 'xapian') referencing a
-       built-in search adapter to use, or an instance of a subclass of
-       :class:`~sphinx.websupport.search.BaseSearch`.
+    search:
+        This may contain either a string (e.g. 'xapian') referencing a
+        built-in search adapter to use, or an instance of a subclass of
+        :class:`~sphinx.websupport.search.BaseSearch`.
 
-   storage:
-       This may contain either a string representing a database uri, or an
-       instance of a subclass of 
-       :class:`~sphinx.websupport.storage.StorageBackend`. If this is not
-       provided a new sqlite database will be created.
+    storage:
+        This may contain either a string representing a database uri, or an
+        instance of a subclass of
+        :class:`~sphinx.websupport.storage.StorageBackend`. If this is not
+        provided a new sqlite database will be created.
 
-   moderation_callback:
-       A callable to be called when a new comment is added that is not
-       displayed. It must accept one argument: a dict representing the 
-       comment that was added.
+    moderation_callback:
+        A callable to be called when a new comment is added that is not
+        displayed. It must accept one argument: a dict representing the
+        comment that was added.
 
-   staticdir:
-       If static files are served from a location besides "/static", this
-       should be a string with the name of that location
-       (e.g. '/static_files').
+    staticdir:
+        If static files are served from a location besides "/static", this
+        should be a string with the name of that location
+        (e.g. '/static_files').
+
+    docroot:
+        If the documentation is not served from the base path of a URL, this
+        should be a string specifying that path (e.g. 'docs')
 
-   docroot:
-       If the documentation is not served from the base path of a URL, this
-       should be a string specifying that path (e.g. 'docs')
-    
 Methods
 ~~~~~~~
 
@@ -64,4 +64,3 @@ Methods
 .. automethod:: sphinx.websupport.WebSupport.process_vote
 
 .. automethod:: sphinx.websupport.WebSupport.get_search_results
-
diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
index 302a4db0e..de9b76558 100644
--- a/doc/web/quickstart.rst
+++ b/doc/web/quickstart.rst
@@ -10,22 +10,22 @@ To make use of the web support package in your application you'll
 need to build the data it uses. This data includes pickle files representing
 documents, search indices, and node data that is used to track where
 comments and other things are in a document. To do this you will need
-to create an instance of the :class:`~sphinx.websupport.WebSupport` 
+to create an instance of the :class:`~sphinx.websupport.WebSupport`
 class and call it's :meth:`~sphinx.websupport.WebSupport.build` method::
 
     from sphinx.websupport import WebSupport
 
     support = WebSupport(srcdir='/path/to/rst/sources/',
                          builddir='/path/to/build/outdir',
-		         search='xapian')
+                         search='xapian')
 
     support.build()
 
 This will read reStructuredText sources from `srcdir` and place the
-necessary data in `builddir`. The `builddir` will contain two 
+necessary data in `builddir`. The `builddir` will contain two
 sub-directories. One named "data" that contains all the data needed
 to display documents, search through documents, and add comments to
-documents. The other directory will be called "static" and contains static 
+documents. The other directory will be called "static" and contains static
 files that should be served from "/static".
 
 .. note::
@@ -40,14 +40,14 @@ Integrating Sphinx Documents Into Your Webapp
 Now that the data is built, it's time to do something useful with it.
 Start off by creating a :class:`~sphinx.websupport.WebSupport` object
 for your application::
-    
+
     from sphinx.websupport import WebSupport
 
     support = WebSupport(datadir='/path/to/the/data',
                          search='xapian')
 
 You'll only need one of these for each set of documentation you will be
-working with. You can then call it's 
+working with. You can then call it's
 :meth:`~sphinx.websupport.WebSupport.get_document` method to access
 individual documents::
 
@@ -56,14 +56,14 @@ individual documents::
 This will return a dictionary containing the following items:
 
 * **body**: The main body of the document as HTML
-* **sidebar**: The sidebar of the document as HTML  
+* **sidebar**: The sidebar of the document as HTML
 * **relbar**: A div containing links to related documents
 * **title**: The title of the document
 * **css**: Links to css files used by Sphinx
 * **js**: Javascript containing comment options
 
 This dict can then be used as context for templates. The goal is to be
-easy to integrate with your existing templating system. An example using 
+easy to integrate with your existing templating system. An example using
 `Jinja2 <http://jinja.pocoo.org/2/>`_ is:
 
 .. sourcecode:: html+jinja
@@ -71,30 +71,30 @@ easy to integrate with your existing templating system. An example using
     {%- extends "layout.html" %}
 
     {%- block title %}
-      {{ document.title }}
+        {{ document.title }}
     {%- endblock %}
 
     {% block css %}
-      {{ super() }}
-      {{ document.css|safe }}
-      <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
+        {{ super() }}
+        {{ document.css|safe }}
+        <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
     {% endblock %}
 
     {%- block js %}
-      {{ super() }}
-      {{ document.js|safe }}
+        {{ super() }}
+        {{ document.js|safe }}
     {%- endblock %}
 
     {%- block relbar %}
-      {{ document.relbar|safe }}
+        {{ document.relbar|safe }}
     {%- endblock %}
 
     {%- block body %}
-      {{ document.body|safe }}
+        {{ document.body|safe }}
     {%- endblock %}
 
     {%- block sidebar %}
-      {{ document.sidebar|safe }}
+        {{ document.sidebar|safe }}
     {%- endblock %}
 
 Authentication
@@ -108,7 +108,7 @@ Once a user has been authenticated you can pass the user's details to certain
 username with comments and votes. The only caveat is that if you allow users
 to change their username you must update the websupport package's data::
 
-   support.update_username(old_username, new_username)
+    support.update_username(old_username, new_username)
 
 *username* should be a unique string which identifies a user, and *moderator*
 should be a boolean representing whether the user has moderation
@@ -121,32 +121,32 @@ a user is logged in and then retrieves a document is::
 
     @app.route('/<path:docname>')
     def doc(docname):
-    	username = g.user.name if g.user else ''
-	moderator = g.user.moderator if g.user else False
-	try:
-	    document = support.get_document(docname, username, moderator)
-	except DocumentNotFoundError:
-	    abort(404)
+        username = g.user.name if g.user else ''
+        moderator = g.user.moderator if g.user else False
+        try:
+            document = support.get_document(docname, username, moderator)
+        except DocumentNotFoundError:
+            abort(404)
         return render_template('doc.html', document=document)
 
 The first thing to notice is that the *docname* is just the request path.
 This makes accessing the correct document easy from a single view.
 If the user is authenticated then the username and moderation status are
-passed along with the docname to 
+passed along with the docname to
 :meth:`~sphinx.websupport.WebSupport.get_document`. The web support package
 will then add this data to the COMMENT_OPTIONS that are used in the template.
 
 .. note::
 
-   This only works works if your documentation is served from your
-   document root. If it is served from another directory, you will
-   need to prefix the url route with that directory, and give the `docroot`
-   keyword argument when creating the web support object::
-   
-       support = WebSupport(...
-                            docroot='docs')
-   
-       @app.route('/docs/<path:docname>')
+    This only works works if your documentation is served from your
+    document root. If it is served from another directory, you will
+    need to prefix the url route with that directory, and give the `docroot`
+    keyword argument when creating the web support object::
+
+        support = WebSupport(...
+                             docroot='docs')
+
+        @app.route('/docs/<path:docname>')
 
 Performing Searches
 ~~~~~~~~~~~~~~~~~~~
@@ -155,7 +155,7 @@ To use the search form built-in to the Sphinx sidebar, create a function
 to handle requests to the url 'search' relative to the documentation root.
 The user's search query will be in the GET parameters, with the key `q`.
 Then use the :meth:`~sphinx.websupport.WebSupport.get_search_results` method
-to retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that 
+to retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that
 would be like this::
 
     @app.route('/search')
@@ -165,7 +165,7 @@ would be like this::
         return render_template('doc.html', document=document)
 
 Note that we used the same template to render our search results as we
-did to render our documents. That's because 
+did to render our documents. That's because
 :meth:`~sphinx.websupport.WebSupport.get_search_results` returns a context
 dict in the same format that
 :meth:`~sphinx.websupport.WebSupport.get_document` does.
@@ -186,22 +186,22 @@ function is used to add a new comment, and will call the web support method
         proposal = request.form.get('proposal', '')
         username = g.user.name if g.user is not None else 'Anonymous'
         comment = support.add_comment(text, node_id='node_id',
-	                              parent_id='parent_id', 
-				      username=username, proposal=proposal)
+                                      parent_id='parent_id',
+                                      username=username, proposal=proposal)
         return jsonify(comment=comment)
 
 You'll notice that both a `parent_id` and `node_id` are sent with the
 request. If the comment is being attached directly to a node, `parent_id`
 will be empty. If the comment is a child of another comment, then `node_id`
-will be empty. Then next function handles the retrieval of comments for a 
-specific node, and is aptly named 
+will be empty. Then next function handles the retrieval of comments for a
+specific node, and is aptly named
 :meth:`~sphinx.websupport.WebSupport.get_data`::
 
     @app.route('/docs/get_comments')
     def get_comments():
         username = g.user.name if g.user else None
-	moderator = g.user.moderator if g.user else False
-	node_id = request.args.get('node', '')
+        moderator = g.user.moderator if g.user else False
+        node_id = request.args.get('node', '')
         data = support.get_data(parent_id, user_id)
         return jsonify(**data)
 
@@ -223,15 +223,15 @@ votes on comments::
 Comment Moderation
 ~~~~~~~~~~~~~~~~~~
 
-By default all comments added through 
+By default all comments added through
 :meth:`~sphinx.websupport.WebSupport.add_comment` are automatically
 displayed. If you wish to have some form of moderation, you can pass
 the `displayed` keyword argument::
 
     comment = support.add_comment(text, node_id='node_id',
-                                  parent_id='parent_id', 
+                                  parent_id='parent_id',
                                   username=username, proposal=proposal,
- 				  displayed=False)
+                                  displayed=False)
 
 You can then create two new views to handle the moderation of comments. The
 first will be called when a moderator decides a comment should be accepted
@@ -240,18 +240,18 @@ and displayed::
     @app.route('/docs/accept_comment', methods=['POST'])
     def accept_comment():
         moderator = g.user.moderator if g.user else False
-	comment_id = request.form.get('id')
-	support.accept_comment(comment_id, moderator=moderator)
-	return 'OK'
+        comment_id = request.form.get('id')
+        support.accept_comment(comment_id, moderator=moderator)
+        return 'OK'
 
 The next is very similar, but used when rejecting a comment::
 
     @app.route('/docs/reject_comment', methods=['POST'])
     def reject_comment():
         moderator = g.user.moderator if g.user else False
-	comment_id = request.form.get('id')
-	support.reject_comment(comment_id, moderator=moderator)
-	return 'OK'
+        comment_id = request.form.get('id')
+        support.reject_comment(comment_id, moderator=moderator)
+        return 'OK'
 
 To perform a custom action (such as emailing a moderator) when a new comment
 is added but not displayed, you can pass callable to the
@@ -265,4 +265,4 @@ object::
                          moderation_callback=moderation_callback)
 
 The moderation callback must take one argument, which will be the same
-comment dict that is returned by add_comment.
\ No newline at end of file
+comment dict that is returned by add_comment.
diff --git a/doc/web/searchadapters.rst b/doc/web/searchadapters.rst
index e03fee81f..a84aa8da1 100644
--- a/doc/web/searchadapters.rst
+++ b/doc/web/searchadapters.rst
@@ -10,26 +10,26 @@ To create a custom search adapter you will need to subclass the
 and pass that as the `search` keyword argument when you create the
 :class:`~sphinx.websupport.WebSupport` object::
 
-   support = Websupport(srcdir=srcdir,
-                        builddir=builddir,
-			search=MySearch())
+    support = Websupport(srcdir=srcdir,
+                         builddir=builddir,
+                         search=MySearch())
 
 For more information about creating a custom search adapter, please see
 the documentation of the :class:`BaseSearch` class below.
 
 .. class:: BaseSearch
 
-   Defines an interface for search adapters.
+    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.
+    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
 
@@ -44,4 +44,3 @@ BaseSearch Methods
 .. automethod:: sphinx.websupport.search.BaseSearch.handle_query
 
 .. automethod:: sphinx.websupport.search.BaseSearch.extract_context
-
diff --git a/doc/web/storagebackends.rst b/doc/web/storagebackends.rst
index 6411bf176..6b701ea38 100644
--- a/doc/web/storagebackends.rst
+++ b/doc/web/storagebackends.rst
@@ -10,16 +10,16 @@ To create a custom storage backend you will need to subclass the
 and pass that as the `storage` keyword argument when you create the
 :class:`~sphinx.websupport.WebSupport` object::
 
-   support = Websupport(srcdir=srcdir,
-                        builddir=builddir,
-			storage=MyStorage())
+    support = Websupport(srcdir=srcdir,
+                         builddir=builddir,
+                         storage=MyStorage())
 
 For more information about creating a custom storage backend, please see
 the documentation of the :class:`StorageBackend` class below.
 
 .. class:: StorageBackend
 
-   Defines an interface for storage backends.
+    Defines an interface for storage backends.
 
 StorageBackend Methods
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -42,4 +42,4 @@ StorageBackend Methods
 
 .. automethod:: sphinx.websupport.storage.StorageBackend.accept_comment
 
-.. automethod:: sphinx.websupport.storage.StorageBackend.reject_comment
\ No newline at end of file
+.. automethod:: sphinx.websupport.storage.StorageBackend.reject_comment
diff --git a/doc/websupport.rst b/doc/websupport.rst
index 59973d745..4d743719d 100644
--- a/doc/websupport.rst
+++ b/doc/websupport.rst
@@ -4,12 +4,12 @@ Sphinx Web Support
 ==================
 
 Sphinx provides a way to easily integrate Sphinx documentation
-into your web application. To learn more read the 
+into your web application. To learn more read the
 :ref:`websupportquickstart`.
 
 .. toctree::
 
-   web/quickstart
-   web/api
-   web/searchadapters
-   web/storagebackends
\ No newline at end of file
+    web/quickstart
+    web/api
+    web/searchadapters
+    web/storagebackends
diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 3d0356b71..23d0f52c4 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -58,7 +58,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     def handle_page(self, pagename, addctx, templatename='page.html',
                     outfilename=None, event_arg=None):
         # This is mostly copied from StandaloneHTMLBuilder. However, instead
-        # of rendering the template and saving the html, create a context 
+        # of rendering the template and saving the html, create a context
         # dict and pickle it.
         ctx = self.globalcontext.copy()
         ctx['pagename'] = pagename
@@ -140,7 +140,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     FILE_SUFFIX: '',
     HAS_SOURCE: '%s'
   };
-</script>""" 
+</script>"""
         opts = opts % (ctx.get('url_root', ''), escape(ctx['release']),
                        str(ctx['has_source']).lower())
         scripts = []
@@ -148,4 +148,3 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
             scripts.append(make_script(file))
         scripts.append(make_script('_static/websupport.js'))
         return opts + '\n' + '\n'.join(scripts)
-
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 76715d14a..17aef4025 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -49,7 +49,7 @@ class WebSupport(object):
         self.moderation_callback = moderation_callback
 
         self._init_templating()
-        self._init_search(search)            
+        self._init_search(search)
         self._init_storage(storage)
 
         self._make_base_comment_options()
@@ -105,7 +105,7 @@ class WebSupport(object):
         doctreedir = path.join(self.outdir, 'doctrees')
         app = WebSupportApp(self.srcdir, self.srcdir,
                             self.outdir, doctreedir, 'websupport',
-                            search=self.search, status=self.status, 
+                            search=self.search, status=self.status,
                             warning=self.warning, storage=self.storage,
                             staticdir=self.staticdir, builddir=self.builddir)
 
@@ -119,8 +119,8 @@ class WebSupport(object):
 
             support = WebSupport(datadir=datadir)
             support.get_document('index', username, moderator)
-            
-        In most cases `docname` will be taken from the request path and 
+
+        In most cases `docname` will be taken from the request path and
         passed directly to this function. In Flask, that would be something
         like this::
 
@@ -139,7 +139,7 @@ class WebSupport(object):
         to be used during template rendering.
 
         * **body**: The main body of the document as HTML
-        * **sidebar**: The sidebar of the document as HTML  
+        * **sidebar**: The sidebar of the document as HTML
         * **relbar**: A div containing links to related documents
         * **title**: The title of the document
         * **css**: Links to css files used by Sphinx
@@ -161,7 +161,7 @@ class WebSupport(object):
         document = pickle.load(f)
         comment_opts = self._make_comment_options(username, moderator)
         comment_metadata = self.storage.get_metadata(docname, moderator)
-                                                             
+
         document['js'] = '\n'.join([comment_opts,
                                     self._make_metadata(comment_metadata),
                                     document['js']])
@@ -172,7 +172,7 @@ class WebSupport(object):
         of search results. Then render the search results as html and
         return a context dict like the one created by
         :meth:`get_document`::
-        
+
             document = support.get_search_results(q)
 
         :param q: the search query
@@ -187,12 +187,12 @@ class WebSupport(object):
         return document
 
     def get_data(self, node_id, username=None, moderator=False):
-        """Get the comments and source associated with `node_id`. If 
-        `username` is given vote information will be included with the 
+        """Get the comments and source associated with `node_id`. If
+        `username` is given vote information will be included with the
         returned comments. The default CommentBackend returns a dict with
         two keys, *source*, and *comments*. *source* is raw source of the
         node and is used as the starting point for proposals a user can
-        add. *comments* is a list of dicts that represent a comment, each 
+        add. *comments* is a list of dicts that represent a comment, each
         having the following items:
 
         ============= ======================================================
@@ -209,12 +209,12 @@ class WebSupport(object):
                       8601 format. `delta` is a printable form of how old
                       the comment is (e.g. "3 hours ago").
         vote          If `user_id` was given, this will be an integer
-                      representing the vote. 1 for an upvote, -1 for a 
+                      representing the vote. 1 for an upvote, -1 for a
                       downvote, or 0 if unvoted.
-        node          The id of the node that the comment is attached to. 
-                      If the comment's parent is another comment rather than 
+        node          The id of the node that the comment is attached to.
+                      If the comment's parent is another comment rather than
                       a node, this will be null.
-        parent        The id of the comment that this comment is attached 
+        parent        The id of the comment that this comment is attached
                       to if it is not attached to a node.
         children      A list of all children, in this format.
         proposal_diff An HTML representation of the differences between the
@@ -232,7 +232,7 @@ class WebSupport(object):
         instead replaces the username and text files with "[deleted]" so
         as not to leave any comments orphaned.
 
-        If `moderator` is True, the comment will always be deleted. If 
+        If `moderator` is True, the comment will always be deleted. If
         `moderator` is False, the comment will only be deleted if the
         `username` matches the `username` on the comment.
 
@@ -246,25 +246,25 @@ class WebSupport(object):
         """
         self.storage.delete_comment(comment_id, username, moderator)
 
-    def add_comment(self, text, node_id='', parent_id='', displayed=True, 
+    def add_comment(self, text, node_id='', parent_id='', displayed=True,
                     username=None, time=None, proposal=None,
                     moderator=False):
-        """Add a comment to a node or another comment. Returns the comment 
-        in the same format as :meth:`get_comments`. If the comment is being 
-        attached to a node, pass in the node's id (as a string) with the 
+        """Add a comment to a node or another comment. Returns the comment
+        in the same format as :meth:`get_comments`. If the comment is being
+        attached to a node, pass in the node's id (as a string) with the
         node keyword argument::
 
             comment = support.add_comment(text, node_id=node_id)
 
         If the comment is the child of another comment, provide the parent's
         id (as a string) with the parent keyword argument::
-            
+
             comment = support.add_comment(text, parent_id=parent_id)
 
         If you would like to store a username with the comment, pass
         in the optional `username` keyword argument::
 
-            comment = support.add_comment(text, node=node_id, 
+            comment = support.add_comment(text, node=node_id,
                                           username=username)
 
         :param parent_id: the prefixed id of the comment's parent.
@@ -274,7 +274,7 @@ class WebSupport(object):
         :param time: the time the comment was created, defaults to now.
         """
         comment = self.storage.add_comment(text, displayed, username,
-                                           time, proposal, node_id, 
+                                           time, proposal, node_id,
                                            parent_id, moderator)
         if not displayed and self.moderation_callback:
             self.moderation_callback(comment)
@@ -282,10 +282,10 @@ class WebSupport(object):
 
     def process_vote(self, comment_id, username, value):
         """Process a user's vote. The web support package relies
-        on the API user to perform authentication. The API user will 
+        on the API user to perform authentication. The API user will
         typically receive a comment_id and value from a form, and then
-        make sure the user is authenticated. A unique username  must be 
-        passed in, which will also be used to retrieve the user's past 
+        make sure the user is authenticated. A unique username  must be
+        passed in, which will also be used to retrieve the user's past
         voting data. An example, once again in Flask::
 
             @app.route('/docs/process_vote', methods=['POST'])
@@ -352,20 +352,20 @@ class WebSupport(object):
         that remains the same throughout the lifetime of the
         :class:`~sphinx.websupport.WebSupport` object.
         """
-        parts = ['<script type="text/javascript">', 
+        parts = ['<script type="text/javascript">',
                  'var COMMENT_OPTIONS = {']
         if self.docroot is not '':
-            parts.append('addCommentURL: "/%s/%s",' % (self.docroot, 
+            parts.append('addCommentURL: "/%s/%s",' % (self.docroot,
                                                        'add_comment'))
-            parts.append('getCommentsURL: "/%s/%s",' % (self.docroot, 
+            parts.append('getCommentsURL: "/%s/%s",' % (self.docroot,
                                                         'get_comments'))
-            parts.append('processVoteURL: "/%s/%s",' % (self.docroot, 
+            parts.append('processVoteURL: "/%s/%s",' % (self.docroot,
                                                         'process_vote'))
-            parts.append('acceptCommentURL: "/%s/%s",' % (self.docroot, 
+            parts.append('acceptCommentURL: "/%s/%s",' % (self.docroot,
                                                           'accept_comment'))
-            parts.append('rejectCommentURL: "/%s/%s",' % (self.docroot, 
+            parts.append('rejectCommentURL: "/%s/%s",' % (self.docroot,
                                                           'reject_comment'))
-            parts.append('deleteCommentURL: "/%s/%s",' % (self.docroot, 
+            parts.append('deleteCommentURL: "/%s/%s",' % (self.docroot,
                                                           'delete_comment'))
 
         if self.staticdir != 'static':
@@ -378,8 +378,8 @@ class WebSupport(object):
             parts.append('upArrowPressed: "/%s",' % p('up-pressed.png'))
             parts.append('downArrowPressed: "/%s",' % p('down-pressed.png'))
 
-        self.base_comment_opts = '\n'.join(parts)            
-            
+        self.base_comment_opts = '\n'.join(parts)
+
     def _make_comment_options(self, username, moderator):
         """Helper method to create the parts of the COMMENT_OPTIONS
         javascript that are unique to each request.
@@ -394,14 +394,13 @@ class WebSupport(object):
         parts.append('moderator: %s' % str(moderator).lower())
         parts.append('};')
         parts.append('</script>')
-        return '\n'.join(parts)            
+        return '\n'.join(parts)
 
     def _make_metadata(self, data):
-        node_js = ', '.join(['%s: %s' % (node_id, comment_count) 
+        node_js = ', '.join(['%s: %s' % (node_id, comment_count)
                              for node_id, comment_count in data.iteritems()])
         js = """
 <script type="text/javascript">
   var COMMENT_METADATA = {%s};
 </script>""" % node_js
         return js
-
diff --git a/sphinx/websupport/search/__init__.py b/sphinx/websupport/search/__init__.py
index 80f91ab1d..cb66618b5 100644
--- a/sphinx/websupport/search/__init__.py
+++ b/sphinx/websupport/search/__init__.py
@@ -34,7 +34,7 @@ class BaseSearch(object):
     def feed(self, pagename, title, doctree):
         """Called by the builder to add a doctree to the index. Converts the
         `doctree` to text and passes it to :meth:`add_document`. You probably
-        won't want to override this unless you need access to the `doctree`. 
+        won't want to override this unless you need access to the `doctree`.
         Override :meth:`add_document` instead.
 
         :param pagename: the name of the page to be indexed
@@ -50,11 +50,11 @@ class BaseSearch(object):
 
         `pagename` is name of the page being indexed. It is the combination
         of the source files relative path and filename,
-        minus the extension. For example, if the source file is 
+        minus the extension. For example, if the source file is
         "ext/builders.rst", the `pagename` would be "ext/builders". This
-        will need to be returned with search results when processing a 
+        will need to be returned with search results when processing a
         query.
-        
+
         :param pagename: the name of the page being indexed
         :param title: the page's title
         :param text: the full text of the page
@@ -62,13 +62,13 @@ class BaseSearch(object):
         raise NotImplementedError()
 
     def query(self, q):
-        """Called by the web support api to get search results. This method 
+        """Called by the web support api to get search results. This method
         compiles the regular expression to be used when
         :meth:`extracting context <extract_context>`, then calls
         :meth:`handle_query`. You won't want to override this unless you
         don't want to use the included :meth:`extract_context` method.
         Override :meth:`handle_query` instead.
-        
+
         :param q: the search query string.
         """
         self.context_re = re.compile('|'.join(q.split()), re.I)
@@ -119,4 +119,3 @@ search_adapters = {
     'whoosh': ('whooshsearch', 'WhooshSearch'),
     'null': ('nullsearch', 'NullSearch')
     }
-
diff --git a/sphinx/websupport/search/xapiansearch.py b/sphinx/websupport/search/xapiansearch.py
index 2f2ffbe59..16c7e2b1b 100644
--- a/sphinx/websupport/search/xapiansearch.py
+++ b/sphinx/websupport/search/xapiansearch.py
@@ -28,7 +28,7 @@ class XapianSearch(BaseSearch):
 
     def init_indexing(self, changed=[]):
         ensuredir(self.db_path)
-        self.database = xapian.WritableDatabase(self.db_path, 
+        self.database = xapian.WritableDatabase(self.db_path,
                                                 xapian.DB_CREATE_OR_OPEN)
         self.indexer = xapian.TermGenerator()
         stemmer = xapian.Stem("english")
diff --git a/sphinx/websupport/storage/__init__.py b/sphinx/websupport/storage/__init__.py
index 24d4ade55..17907e992 100644
--- a/sphinx/websupport/storage/__init__.py
+++ b/sphinx/websupport/storage/__init__.py
@@ -20,13 +20,13 @@ class StorageBackend(object):
         """Add a node to the StorageBackend.
 
         :param document: the name of the document the node belongs to.
-        
+
         :param line: the line in the source where the node begins.
 
         :param source: the source files name.
         """
         raise NotImplementedError()
-    
+
     def post_build(self):
         """Called after a build has completed. Use this to finalize the
         addition of nodes if needed.
@@ -36,7 +36,7 @@ class StorageBackend(object):
     def add_comment(self, text, displayed, username, time,
                     proposal, node_id, parent_id, moderator):
         """Called when a comment is being added.
-        
+
         :param text: the text of the comment
         :param displayed: whether the comment should be displayed
         :param username: the name of the user adding the comment
diff --git a/sphinx/websupport/storage/db.py b/sphinx/websupport/storage/db.py
index 4a84cd086..74a3e2b70 100644
--- a/sphinx/websupport/storage/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -81,7 +81,7 @@ class Node(Base):
             comment, vote = r if username else (r, 0)
 
             inheritance_chain = comment.path.split('.')[1:]
-            
+
             if len(inheritance_chain) == len(list_stack) + 1:
                 parent = list_stack[-1][-1]
                 list_stack.append(parent['children'])
@@ -90,7 +90,7 @@ class Node(Base):
                     list_stack.pop()
 
             list_stack[-1].append(comment.serializable(vote=vote))
-        
+
         return comments
 
     def __init__(self, document, line, source):
@@ -115,7 +115,7 @@ class Comment(Base):
     node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
     node = relation(Node, backref="comments")
 
-    def __init__(self, text, displayed, username, rating, time, 
+    def __init__(self, text, displayed, username, rating, time,
                  proposal, proposal_diff):
         self.text = text
         self.displayed = displayed
diff --git a/sphinx/websupport/storage/differ.py b/sphinx/websupport/storage/differ.py
index 068d7e6fc..f0b6a8ea5 100644
--- a/sphinx/websupport/storage/differ.py
+++ b/sphinx/websupport/storage/differ.py
@@ -53,12 +53,12 @@ class CombinedHtmlDiff(object):
             return text
         elif prefix == '?':
             return ''
-        
+
         if next is not None and next[0] == '?':
             tag = 'ins' if prefix == '+' else 'del'
             text = self._highlight_text(text, next, tag)
         css_class = 'prop_added' if prefix == '+' else 'prop_removed'
-        
+
         return '<span class="%s">%s</span>\n' % (css_class, text.rstrip())
 
     def _highlight_text(self, text, next, tag):
@@ -76,4 +76,3 @@ class CombinedHtmlDiff(object):
             start = match.end()
         new_text.append(text[start:])
         return ''.join(new_text)
-
diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
index 1aaa84738..e2cd87ac5 100644
--- a/sphinx/websupport/storage/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -21,7 +21,7 @@ from sphinx.websupport.storage.db import Base, Node, Comment, CommentVote,\
 from sphinx.websupport.storage.differ import CombinedHtmlDiff
 
 class SQLAlchemyStorage(StorageBackend):
-    """A :class:`~sphinx.websupport.storage.StorageBackend` using 
+    """A :class:`~sphinx.websupport.storage.StorageBackend` using
     SQLAlchemy.
     """
     def __init__(self, engine):
@@ -59,7 +59,7 @@ class SQLAlchemyStorage(StorageBackend):
                 raise CommentNotAllowedError(
                     "Can't add child to a parent that is not displayed")
 
-        comment = Comment(text, displayed, username, 0, 
+        comment = Comment(text, displayed, username, 0,
                           time or datetime.now(), proposal, proposal_diff)
         session.add(comment)
         session.flush()
@@ -88,7 +88,7 @@ class SQLAlchemyStorage(StorageBackend):
     def get_metadata(self, docname, moderator):
         session = Session()
         subquery = session.query(
-            Comment.id, Comment.node_id, 
+            Comment.id, Comment.node_id,
             func.count('*').label('comment_count')).group_by(
             Comment.node_id).subquery()
         nodes = session.query(Node.id, subquery.c.comment_count).outerjoin(
diff --git a/tests/test_searchadapters.py b/tests/test_searchadapters.py
index cb6c6e968..a30141dfd 100644
--- a/tests/test_searchadapters.py
+++ b/tests/test_searchadapters.py
@@ -27,7 +27,7 @@ def teardown_module():
 
 def search_adapter_helper(adapter):
     clear_builddir()
-    
+
     settings = {'builddir': os.path.join(test_root, 'websupport'),
                 'status': StringIO(),
                 'warning': StringIO()}
@@ -81,4 +81,3 @@ def test_whoosh():
     except ImportError:
         sys.stderr.write('info: not running whoosh tests, ' \
                          'whoosh doesn\'t seem to be installed')
-
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 27a14e369..32249976d 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -64,7 +64,7 @@ def test_build(support):
 @with_support()
 def test_get_document(support):
     raises(DocumentNotFoundError, support.get_document, 'nonexisting')
-    
+
     contents = support.get_document('contents')
     assert contents['title'] and contents['body'] \
         and contents['sidebar'] and contents['relbar']
@@ -78,27 +78,27 @@ def test_comments(support):
     second_node = nodes[1]
 
     # Create a displayed comment and a non displayed comment.
-    comment = support.add_comment('First test comment', 
+    comment = support.add_comment('First test comment',
                                   node_id=str(first_node.id),
                                   username='user_one')
-    hidden_comment = support.add_comment('Hidden comment', 
-                                         node_id=str(first_node.id), 
+    hidden_comment = support.add_comment('Hidden comment',
+                                         node_id=str(first_node.id),
                                          displayed=False)
     # Make sure that comments can't be added to a comment where
     # displayed == False, since it could break the algorithm that
     # converts a nodes comments to a tree.
-    raises(CommentNotAllowedError, support.add_comment, 'Not allowed', 
+    raises(CommentNotAllowedError, support.add_comment, 'Not allowed',
            parent_id=str(hidden_comment['id']))
     # Add a displayed and not displayed child to the displayed comment.
     support.add_comment('Child test comment', parent_id=str(comment['id']),
                         username='user_one')
-    support.add_comment('Hidden child test comment', 
+    support.add_comment('Hidden child test comment',
                         parent_id=str(comment['id']), displayed=False)
     # Add a comment to another node to make sure it isn't returned later.
-    support.add_comment('Second test comment', 
+    support.add_comment('Second test comment',
                         node_id=str(second_node.id),
                         username='user_two')
-    
+
     # Access the comments as a moderator.
     data = support.get_data(str(first_node.id), moderator=True)
     comments = data['comments']
@@ -130,7 +130,7 @@ def test_voting(support):
         data = support.get_data(str(node.id))
         comment = data['comments'][0]
         assert comment['rating'] == val, '%s != %s' % (comment['rating'], val)
-        
+
     support.process_vote(comment['id'], 'user_one', '1')
     support.process_vote(comment['id'], 'user_two', '1')
     support.process_vote(comment['id'], 'user_three', '1')
@@ -161,7 +161,7 @@ def test_proposals(support):
     source = data['source']
     proposal = source[:5] + source[10:15] + 'asdf' + source[15:]
 
-    comment = support.add_comment('Proposal comment', 
+    comment = support.add_comment('Proposal comment',
                                   node_id=str(node.id),
                                   proposal=proposal)
 
@@ -195,7 +195,7 @@ def test_moderator_delete_comments(support):
         return support.get_data(str(node.id), moderator=True)['comments'][1]
 
     comment = get_comment()
-    support.delete_comment(comment['id'], username='user_two', 
+    support.delete_comment(comment['id'], username='user_two',
                            moderator=True)
     comment = get_comment()
     assert comment['username'] == '[deleted]'
@@ -228,9 +228,9 @@ def moderation_callback(comment):
 
 @with_support(moderation_callback=moderation_callback)
 def test_moderation(support):
-    accepted = support.add_comment('Accepted Comment', node_id=3, 
+    accepted = support.add_comment('Accepted Comment', node_id=3,
                                    displayed=False)
-    rejected = support.add_comment('Rejected comment', node_id=3, 
+    rejected = support.add_comment('Rejected comment', node_id=3,
                                    displayed=False)
     # Make sure the moderation_callback is called.
     assert called == True
@@ -248,7 +248,7 @@ def test_moderation(support):
 def test_differ():
     differ = CombinedHtmlDiff()
     source = 'Lorem ipsum dolor sit amet,\nconsectetur adipisicing elit,\n' \
-        'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.' 
+        'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
     prop = 'Lorem dolor sit amet,\nconsectetur nihil adipisicing elit,\n' \
         'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
     differ.make_html(source, prop)

From 82353ffc46a8527cfa40332314f60ccff21991fb Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 10 Aug 2010 12:49:12 -0500
Subject: [PATCH 101/127] fixed typo

---
 sphinx/builders/websupport.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 3d0356b71..e789ead59 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -82,7 +82,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
 
         # Create a dict that will be pickled and used by webapps.
         css = '<link rel="stylesheet" href="%s" type=text/css />' % \
-            pathto('_static/pygmentcs.css', 1)
+            pathto('_static/pygment.css', 1)
         doc_ctx = {'body': ctx.get('body', ''),
                    'title': ctx.get('title', ''),
                    'css': css,

From 51bf5c4240459b8b0d6b79f5b9dd9ee3cb598346 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 10 Aug 2010 13:04:23 -0500
Subject: [PATCH 102/127] fixed ajax-loader.gif path

---
 sphinx/themes/basic/static/websupport.js | 4 +++-
 sphinx/websupport/__init__.py            | 1 +
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 99d1a2217..11d812fdd 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -718,7 +718,8 @@
 	<a href="#" class="sort_option" id="age">oldest</a>\
       </p>\
       </form>\
-      <h3 id="comment_notification">loading comments... <img src="/static/ajax-loader.gif" alt="" /></h3>\
+      <h3 id="comment_notification">loading comments... <img src="' +
+      opts.loadingImage + '" alt="" /></h3>\
       <ul id="comment_ul"></ul>\
     </div>\
     <div id="focuser"></div>';
@@ -732,6 +733,7 @@
     rejectCommentURL: '/reject_comment',
     rejectCommentURL: '/delete_comment',
     commentImage: '/static/_static/comment.png',
+    loadingImage: '/static/_static/comment.png',
     commentBrightImage: '/static/_static/comment-bright.png',
     upArrow: '/static/_static/up.png',
     downArrow: '/static/_static/down.png',
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 76715d14a..2ac195def 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -371,6 +371,7 @@ class WebSupport(object):
         if self.staticdir != 'static':
             p = lambda file: '%s/_static/%s' % (self.staticdir, file)
             parts.append('commentImage: "/%s",' % p('comment.png') )
+            parts.append('loadingImage: "/%s",' % p('ajax-loader.gif') )
             parts.append(
                 'commentBrightImage: "/%s",' % p('comment-bright.png') )
             parts.append('upArrow: "/%s",' % p('up.png'))

From 9545df0d5645212ca0aaf3560ff6000c80d99c7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Tue, 10 Aug 2010 20:09:07 +0200
Subject: [PATCH 103/127] Don't create Javascript by ourselves, we have
 sphinx.util.jsonimpl.dumps for that

---
 sphinx/websupport/__init__.py | 80 +++++++++++++++++------------------
 1 file changed, 40 insertions(+), 40 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 17aef4025..1b33dfa3e 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -11,6 +11,7 @@
 
 import sys
 import cPickle as pickle
+import posixpath
 from os import path
 from datetime import datetime
 
@@ -18,6 +19,7 @@ from jinja2 import Environment, FileSystemLoader
 
 from sphinx.application import Sphinx
 from sphinx.util.osutil import ensuredir
+from sphinx.util.jsonimpl import dumps as dump_json
 from sphinx.websupport.search import BaseSearch, search_adapters
 from sphinx.websupport.storage import StorageBackend
 from sphinx.websupport.errors import *
@@ -352,33 +354,28 @@ class WebSupport(object):
         that remains the same throughout the lifetime of the
         :class:`~sphinx.websupport.WebSupport` object.
         """
-        parts = ['<script type="text/javascript">',
-                 'var COMMENT_OPTIONS = {']
-        if self.docroot is not '':
-            parts.append('addCommentURL: "/%s/%s",' % (self.docroot,
-                                                       'add_comment'))
-            parts.append('getCommentsURL: "/%s/%s",' % (self.docroot,
-                                                        'get_comments'))
-            parts.append('processVoteURL: "/%s/%s",' % (self.docroot,
-                                                        'process_vote'))
-            parts.append('acceptCommentURL: "/%s/%s",' % (self.docroot,
-                                                          'accept_comment'))
-            parts.append('rejectCommentURL: "/%s/%s",' % (self.docroot,
-                                                          'reject_comment'))
-            parts.append('deleteCommentURL: "/%s/%s",' % (self.docroot,
-                                                          'delete_comment'))
+        comment_urls = [
+            ('addCommentURL', 'add_comment'),
+            ('getCommentsURL', 'get_comments'),
+            ('processVoteURL', 'process_vote'),
+            ('acceptCommentURL', 'accept_comment'),
+            ('rejectCommentURL', 'reject_comment'),
+            ('deleteCommentURL', 'delete_comment')
+        ]
+        static_urls = [
+            ('commentImage', 'comment.png'),
+            ('commentBrightImage', 'comment-bright.png'),
+            ('upArrow', 'up.png'),
+            ('upArrowPressed', 'up-pressed.png'),
+            ('downArrow', 'down.png'),
+            ('downArrowPressed', 'down-pressed.png')
+        ]
 
-        if self.staticdir != 'static':
-            p = lambda file: '%s/_static/%s' % (self.staticdir, file)
-            parts.append('commentImage: "/%s",' % p('comment.png') )
-            parts.append(
-                'commentBrightImage: "/%s",' % p('comment-bright.png') )
-            parts.append('upArrow: "/%s",' % p('up.png'))
-            parts.append('downArrow: "/%s",' % p('down.png'))
-            parts.append('upArrowPressed: "/%s",' % p('up-pressed.png'))
-            parts.append('downArrowPressed: "/%s",' % p('down-pressed.png'))
-
-        self.base_comment_opts = '\n'.join(parts)
+        self.base_comment_opts = {}
+        for key, value in comment_urls:
+            self.base_comment_opts[key] = posixpath.join(self.docroot, value)
+        for key, value in static_urls:
+            self.base_comment_opts[key] = posixpath.join(self.staticdir, value)
 
     def _make_comment_options(self, username, moderator):
         """Helper method to create the parts of the COMMENT_OPTIONS
@@ -388,19 +385,22 @@ class WebSupport(object):
         :param moderator: Whether the user making the request is a moderator.
         """
         parts = [self.base_comment_opts]
-        if username is not '':
-            parts.append('voting: true,')
-            parts.append('username: "%s",' % username)
-        parts.append('moderator: %s' % str(moderator).lower())
-        parts.append('};')
-        parts.append('</script>')
-        return '\n'.join(parts)
+        rv = self.base_comment_opts.copy()
+        if username:
+            rv.update({
+                'voting': True,
+                'username': username,
+                'moderator': str(moderator).lower(),
+            })
+        return '\n'.join([
+            '<script type="text/javascript">',
+            'var COMMENT_OPTIONS = %s;' % dump_json(rv),
+            '</script>'
+        ])
 
     def _make_metadata(self, data):
-        node_js = ', '.join(['%s: %s' % (node_id, comment_count)
-                             for node_id, comment_count in data.iteritems()])
-        js = """
-<script type="text/javascript">
-  var COMMENT_METADATA = {%s};
-</script>""" % node_js
-        return js
+        return '\n'.join([
+            '<script type="text/javascript">',
+            'var COMMENT_METADATA = %s;' % dump_json(data),
+            '</script>'
+        ])

From 1ca2903d16bdf0c5e683078292895976874906db Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 10 Aug 2010 14:40:11 -0500
Subject: [PATCH 104/127] That typo I fixed... still not right... *slaps self
 in face*

---
 sphinx/builders/websupport.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index c1decde41..30cf28314 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -82,7 +82,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
 
         # Create a dict that will be pickled and used by webapps.
         css = '<link rel="stylesheet" href="%s" type=text/css />' % \
-            pathto('_static/pygment.css', 1)
+            pathto('_static/pygments.css', 1)
         doc_ctx = {'body': ctx.get('body', ''),
                    'title': ctx.get('title', ''),
                    'css': css,

From 2ca339557d1da7c1e05af5ea4bfa4717b7389e01 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Tue, 10 Aug 2010 21:50:48 +0200
Subject: [PATCH 105/127] Switch to sphinx.util.jsonimpl.dumps in the builder

---
 sphinx/builders/websupport.py | 32 +++++++++++++++-----------------
 1 file changed, 15 insertions(+), 17 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index c1decde41..a801eada2 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -17,6 +17,7 @@ import shutil
 from docutils.io import StringOutput
 
 from sphinx.util.osutil import os_path, relative_uri, ensuredir, copyfile
+from sphinx.util.jsonimpl import dumps as dump_json
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.writers.websupport import WebSupportTranslator
 
@@ -131,20 +132,17 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
             path = ctx['pathto'](file, 1)
             return '<script type="text/javascript" src="%s"></script>' % path
 
-        opts = """
-<script type="text/javascript">
-  var DOCUMENTATION_OPTIONS = {
-    URL_ROOT: '%s',
-    VERSION: '%s',
-    COLLAPSE_INDEX: false,
-    FILE_SUFFIX: '',
-    HAS_SOURCE: '%s'
-  };
-</script>"""
-        opts = opts % (ctx.get('url_root', ''), escape(ctx['release']),
-                       str(ctx['has_source']).lower())
-        scripts = []
-        for file in ctx['script_files']:
-            scripts.append(make_script(file))
-        scripts.append(make_script('_static/websupport.js'))
-        return opts + '\n' + '\n'.join(scripts)
+        opts = {
+            'URL_ROOT': ctx.get('url_root', ''),
+            'VERSION': ctx['release'],
+            'COLLAPSE_INDEX': False,
+            'FILE_SUFFIX': '',
+            'HAS_SOURCE': ctx['has_source']
+        }
+        scripts = [make_script('_static/websupport.js')]
+        scripts += [make_script(file) for file in ctx['script_files']]
+        return '\n'.join([
+            '<script type="text/javascript">'
+            'var DOCUMENTATION_OPTIONS = %s;' % dump_json(opts),
+            '</script>'
+        ] + scripts)

From eb2557f479ec5d5eee2bf260983a7c63e37f77be Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 10 Aug 2010 14:59:22 -0500
Subject: [PATCH 106/127] move opts in js

---
 sphinx/themes/basic/static/websupport.js | 37 ++++++++++++------------
 1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 11d812fdd..2e43c7324 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -632,6 +632,24 @@
     });
   };
 
+  var opts = jQuery.extend({
+    processVoteURL: '/process_vote',
+    addCommentURL: '/add_comment',
+    getCommentsURL: '/get_comments',
+    acceptCommentURL: '/accept_comment',
+    rejectCommentURL: '/reject_comment',
+    rejectCommentURL: '/delete_comment',
+    commentImage: '/static/_static/comment.png',
+    loadingImage: '/static/_static/ajax-loader.gif',
+    commentBrightImage: '/static/_static/comment-bright.png',
+    upArrow: '/static/_static/up.png',
+    downArrow: '/static/_static/down.png',
+    upArrowPressed: '/static/_static/up-pressed.png',
+    downArrowPressed: '/static/_static/down-pressed.png',
+    voting: false,
+    moderator: false
+  }, COMMENT_OPTIONS);
+
   var replyTemplate = '    <li>\
       <div class="reply_div" id="rd<%id%>">\
 	<form id="rf<%id%>">\
@@ -724,25 +742,6 @@
     </div>\
     <div id="focuser"></div>';
 
-
-  var opts = jQuery.extend({
-    processVoteURL: '/process_vote',
-    addCommentURL: '/add_comment',
-    getCommentsURL: '/get_comments',
-    acceptCommentURL: '/accept_comment',
-    rejectCommentURL: '/reject_comment',
-    rejectCommentURL: '/delete_comment',
-    commentImage: '/static/_static/comment.png',
-    loadingImage: '/static/_static/comment.png',
-    commentBrightImage: '/static/_static/comment-bright.png',
-    upArrow: '/static/_static/up.png',
-    downArrow: '/static/_static/down.png',
-    upArrowPressed: '/static/_static/up-pressed.png',
-    downArrowPressed: '/static/_static/down-pressed.png',
-    voting: false,
-    moderator: false
-  }, COMMENT_OPTIONS);
-
   $(document).ready(function() {
     init();
   });

From 1068ece635731ca80dbcdb777600d60513170d63 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 10 Aug 2010 15:07:30 -0500
Subject: [PATCH 107/127] fix paths in js

---
 sphinx/websupport/__init__.py | 48 +++++++++++++++++++----------------
 1 file changed, 26 insertions(+), 22 deletions(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 6fa9cf338..dc0361bd8 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -354,29 +354,33 @@ class WebSupport(object):
         that remains the same throughout the lifetime of the
         :class:`~sphinx.websupport.WebSupport` object.
         """
-        comment_urls = [
-            ('addCommentURL', 'add_comment'),
-            ('getCommentsURL', 'get_comments'),
-            ('processVoteURL', 'process_vote'),
-            ('acceptCommentURL', 'accept_comment'),
-            ('rejectCommentURL', 'reject_comment'),
-            ('deleteCommentURL', 'delete_comment')
-        ]
-        static_urls = [
-            ('commentImage', 'comment.png'),
-            ('loadingImage', 'ajax-loader.gif'),
-            ('commentBrightImage', 'comment-bright.png'),
-            ('upArrow', 'up.png'),
-            ('upArrowPressed', 'up-pressed.png'),
-            ('downArrow', 'down.png'),
-            ('downArrowPressed', 'down-pressed.png')
-        ]
-
         self.base_comment_opts = {}
-        for key, value in comment_urls:
-            self.base_comment_opts[key] = posixpath.join(self.docroot, value)
-        for key, value in static_urls:
-            self.base_comment_opts[key] = posixpath.join(self.staticdir, value)
+
+        if self.docroot is not '':
+            comment_urls = [
+                ('addCommentURL', 'add_comment'),
+                ('getCommentsURL', 'get_comments'),
+                ('processVoteURL', 'process_vote'),
+                ('acceptCommentURL', 'accept_comment'),
+                ('rejectCommentURL', 'reject_comment'),
+                ('deleteCommentURL', 'delete_comment')
+            ]
+            for key, value in comment_urls:
+                self.base_comment_opts[key] = \
+                    '/' + posixpath.join(self.docroot, value)
+        if self.staticdir != 'static':
+            static_urls = [
+                ('commentImage', 'comment.png'),
+                ('loadingImage', 'ajax-loader.gif'),
+                ('commentBrightImage', 'comment-bright.png'),
+                ('upArrow', 'up.png'),
+                ('upArrowPressed', 'up-pressed.png'),
+                ('downArrow', 'down.png'),
+                ('downArrowPressed', 'down-pressed.png')
+            ]
+            for key, value in static_urls:
+                self.base_comment_opts[key] = \
+                    '/' + posixpath.join(self.staticdir, '_static', value)
 
     def _make_comment_options(self, username, moderator):
         """Helper method to create the parts of the COMMENT_OPTIONS

From 8c83ca35c97ee70d45c20494715d6b20e5d7342f Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 10 Aug 2010 18:42:18 -0500
Subject: [PATCH 108/127] Don't need to convert moderator to string anymore

---
 sphinx/websupport/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index dc0361bd8..cc065b7f7 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -395,7 +395,7 @@ class WebSupport(object):
             rv.update({
                 'voting': True,
                 'username': username,
-                'moderator': str(moderator).lower(),
+                'moderator': moderator,
             })
         return '\n'.join([
             '<script type="text/javascript">',

From 1b99787dcdfcc388cb69193a14dc09dbeab0bc58 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Tue, 10 Aug 2010 19:51:21 -0500
Subject: [PATCH 109/127] changed comment.png to faded image.

---
 sphinx/themes/basic/static/comment.png | Bin 3501 -> 3445 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)

diff --git a/sphinx/themes/basic/static/comment.png b/sphinx/themes/basic/static/comment.png
index bad742bb08696f9103edeb65b301e514d1bb81de..92feb52b8824c6b0f59b658b1196c61de9162a95 100644
GIT binary patch
delta 725
zcmV;`0xJEj8}%BntqOk#3ji@Y?^d_J0007~Nkl<ZILmdB%WK?K6vsc`b7!11)Y$lF
zs)Aq?6Sa-0)<-c4QUy_hl<pMVxNs%tLaO)|lx`w|V$hACSQJVL6^kx3Rt#xc@D(E?
zR6A{>6SX0oG@1P7p5tQTP_2G9_j2y}KF+yf9e3~jhGYAN7#n{(plv&cZ>p5jjX~Vt
z&W0e)wpw1RFRuRd<fFsqxCjCmeC`BuuieS`d(-_phOc?QyHdKP@VLS~$T=u-02Ik|
zrdDsfzWbrA`$zZ9F|l_L?cV<*2VWfE)2X=~n|r&z?CvU+n?)w)pyeTtfPjd=gD96w
z=ayEV-*xZ6tDS!YZylWJ9~tWV!QryC!jVLdzyJ?`AW(#dvPYDYH2>$y3y+W7IwpXx
z=YE;$?ke50)^cT!h;`u(IthXZ;o*T(tt~9yRhpcsUZ0Zsn?)wKnMwj#Tf-et;2~0o
z>>ff2#g^Wl%9c_<U(WQ%kbq=DW*zgCfCv;$c1UKzog#neGT2ng?p>{jQW=qwkPNf-
z3~Hw*Lf{707BPurWI<tTg)c<JvP1}l36exIk<3UYOkgHVh6yA^cq}%HeAa$nT&bPE
zP@ItrB$){PO-Nu#n5jLV6rez;v08lf$j-q90ep0HcC=?><<OOvS5#Ujr1diba*oLE
zYGoqawRnHNIe-85o38_~S3U_I8@X*_snL95d8LSzW=2wYdw1<62oXdQ`t^_Hxmvxk
z9f09O?f>5V^d$9n9%TH$^zhb!tKLYaZCCeh=mvCQwJ3@lO+0=(IluJbo?SyP@n5*(
z<)1tE$>Y_JtEcAUixbr&6Q6ziz~Ra7Zy*0)dQ(lO;o7(PUmQL<J9zB7lcztQsUCUr
z-KmZLe0}DUe*1S}Z7naJt~VZ@J-#sd>{ItO=)2hMQs=(_n!ZpXD%P(H00000NkvXX
Hu0mjf_7rZ@

delta 782
zcmV+p1M&Rz8m$|!tqOkz1r-M@pqmTC0008tNkl<ZILn2RUuf246vw~kJkRg9_x11W
zVon0J6*?w5rxj9&)J+gbh;-{kL3mN1gv@ei;6;fUjY#OvF4Qhw!l)sIo88PD3L|X}
z*`~wB-pxOI=XAb*eD`~v=NvD7YuJVL<y;&%U%uyaID|R9)OvpveMdF`*h=qroP2)8
zvgkP{x^mWORzz>jRD8bs%7c-c$2Z@{6Cwa;{NOT%zS;z|oNGAQ-ke)imt9kFva~!a
zC{+cOBmfE*8=5%PQ#jspsOjkTBSSdT+6dZlbQnMHTZ`S_-F)$lmfGHi`fPM}#-ox1
zloL?Z2}BhkD7=5DK9e=nJNR(V*YB)upC`cf3k|);ng<g_JXs82A_NgA5g>}7KoHf$
zD|s)vC}!&HySMlBo;6<*0Q}T9eQ8x)=H=;fphr&BD-kmQP47&%1I`OvP$XWIRd1a5
zeR8vH%jKV4m^BTBQoyWN5D{e~0&@zd3WOkV0bpVfiHd&`d58K}o0inu04y)f>Jnpx
zjA6uv5Je1T0?h@uK;R%C0stme!1<6d2DP?a4ViKxwl=niEg_B=ktIYX4G;y4XCw>|
zBqdUYWeKF@>~zr;oR_j?T5Jsv8KO+Yh-^wBqA)Cg15^NO0^$G_(FaoxtGD<<e<6Q8
zUzxC$!OVYT4QpfxH8G(k25Mp;j#DaYSgm0-mS}jabn)BwUMTSB_pemPZkJjwU!Oq;
z3d0~`f-!_ljroT}4HGa|gMSxqf3a)zP5|Ho=M=dQo6cMvnR#n;qO4<uDws%p0K8WK
z1j`^1=mJ*y?b77XiSF?h0Kmr1^v`v>&Zo_`?u~z+caC3d@48zWxaVYG%IUAyib<~T
ze(}^Fg^?}$|N0D1Q}aio^L^Wo`LloCN%WJ``K~t)_iugs(}8t({cP>LVMWJNbFlN+
zaN{>UQ{x}!#=5Znmqq`czKj3WwuAlkueDuiMD~Xm0I<B{KmCsZzk6ggYXo`_00000
MNks-uM6N<$g3my5+5i9m


From 1d4c7d4fe01bc768ebb0bfc9765f58a86dcc74c6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Wed, 11 Aug 2010 14:23:58 +0200
Subject: [PATCH 110/127] Added initial versioning support

---
 sphinx/builders/websupport.py                 | 38 +++++++++++++++++++
 sphinx/websupport/storage/__init__.py         |  4 +-
 sphinx/websupport/storage/db.py               |  8 ++--
 .../websupport/storage/sqlalchemystorage.py   |  4 +-
 sphinx/writers/websupport.py                  |  3 +-
 tests/test_websupport.py                      | 26 +++++++------
 6 files changed, 65 insertions(+), 18 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 8cc70ea0c..e1bd80111 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -12,14 +12,23 @@
 import cPickle as pickle
 from os import path
 from cgi import escape
+from glob import glob
+import os
 import posixpath
 import shutil
+
 from docutils.io import StringOutput
+from docutils.utils import Reporter
 
 from sphinx.util.osutil import os_path, relative_uri, ensuredir, copyfile
 from sphinx.util.jsonimpl import dumps as dump_json
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.writers.websupport import WebSupportTranslator
+from sphinx.environment import WarningStream
+from sphinx.versioning import add_uids, merge_doctrees
+
+def is_paragraph(node):
+    return node.__class__.__name__ == 'paragraph'
 
 class WebSupportBuilder(StandaloneHTMLBuilder):
     """
@@ -28,13 +37,39 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
     name = 'websupport'
     out_suffix = '.fpickle'
 
+    def init(self):
+        StandaloneHTMLBuilder.init(self)
+        for f in glob(path.join(self.doctreedir, '*.doctree')):
+            copyfile(f, f + '.old')
+
     def init_translator_class(self):
         self.translator_class = WebSupportTranslator
 
+    def get_old_doctree(self, docname):
+        fp = self.env.doc2path(docname, self.doctreedir, '.doctree.old')
+        try:
+            f = open(fp, 'rb')
+            try:
+                doctree = pickle.load(f)
+            finally:
+                f.close()
+        except IOError:
+            return None
+        doctree.settings.env = self.env
+        doctree.reporter = Reporter(self.env.doc2path(docname), 2, 5,
+                                    stream=WarningStream(self.env._warnfunc))
+        return doctree
+
     def write_doc(self, docname, doctree):
         destination = StringOutput(encoding='utf-8')
         doctree.settings = self.docsettings
 
+        old_doctree = self.get_old_doctree(docname)
+        if old_doctree:
+            list(merge_doctrees(old_doctree, doctree, is_paragraph))
+        else:
+            list(add_uids(doctree, is_paragraph))
+
         self.cur_docname = docname
         self.secnumbers = self.env.toc_secnumbers.get(docname, {})
         self.imgpath = '/' + posixpath.join(self.app.staticdir, '_images')
@@ -123,6 +158,9 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
         shutil.move(path.join(self.outdir, '_static'),
                     path.join(self.app.builddir, self.app.staticdir,
                               '_static'))
+        for f in glob(path.join(self.doctreedir, '*.doctree.old')):
+            os.remove(f)
+
 
     def dump_search_index(self):
         self.indexer.finish_indexing()
diff --git a/sphinx/websupport/storage/__init__.py b/sphinx/websupport/storage/__init__.py
index 17907e992..da815d0a3 100644
--- a/sphinx/websupport/storage/__init__.py
+++ b/sphinx/websupport/storage/__init__.py
@@ -16,9 +16,11 @@ class StorageBackend(object):
         """
         pass
 
-    def add_node(self, document, line, source):
+    def add_node(self, id, document, line, source):
         """Add a node to the StorageBackend.
 
+        :param id: a unique id for the comment.
+
         :param document: the name of the document the node belongs to.
 
         :param line: the line in the source where the node begins.
diff --git a/sphinx/websupport/storage/db.py b/sphinx/websupport/storage/db.py
index 74a3e2b70..54b16f225 100644
--- a/sphinx/websupport/storage/db.py
+++ b/sphinx/websupport/storage/db.py
@@ -11,6 +11,7 @@
 """
 
 from datetime import datetime
+from uuid import uuid4
 
 from sqlalchemy import Column, Integer, Text, String, Boolean, ForeignKey,\
                        DateTime
@@ -28,7 +29,7 @@ class Node(Base):
     """Data about a Node in a doctree."""
     __tablename__ = db_prefix + 'nodes'
 
-    id = Column(Integer, primary_key=True)
+    id = Column(String(32), primary_key=True)
     document = Column(String(256), nullable=False)
     line = Column(Integer)
     source = Column(Text, nullable=False)
@@ -93,7 +94,8 @@ class Node(Base):
 
         return comments
 
-    def __init__(self, document, line, source):
+    def __init__(self, id, document, line, source):
+        self.id = id
         self.document = document
         self.line = line
         self.source = source
@@ -112,7 +114,7 @@ class Comment(Base):
     proposal_diff = Column(Text)
     path = Column(String(256), index=True)
 
-    node_id = Column(Integer, ForeignKey(db_prefix + 'nodes.id'))
+    node_id = Column(String, ForeignKey(db_prefix + 'nodes.id'))
     node = relation(Node, backref="comments")
 
     def __init__(self, text, displayed, username, rating, time,
diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py
index e2cd87ac5..d1683f603 100644
--- a/sphinx/websupport/storage/sqlalchemystorage.py
+++ b/sphinx/websupport/storage/sqlalchemystorage.py
@@ -33,8 +33,8 @@ class SQLAlchemyStorage(StorageBackend):
     def pre_build(self):
         self.build_session = Session()
 
-    def add_node(self, document, line, source):
-        node = Node(document, line, source)
+    def add_node(self, id, document, line, source):
+        node = Node(id, document, line, source)
         self.build_session.add(node)
         self.build_session.flush()
         return node
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 05bc2c8b3..306cfd869 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -55,7 +55,8 @@ class WebSupportTranslator(HTMLTranslator):
 
     def add_db_node(self, node):
         storage = self.builder.app.storage
-        db_node_id = storage.add_node(document=self.builder.cur_docname,
+        db_node_id = storage.add_node(id=node.uid,
+                                      document=self.builder.cur_docname,
                                       line=node.line,
                                       source=node.rawsource or node.astext())
         return db_node_id
diff --git a/tests/test_websupport.py b/tests/test_websupport.py
index 32249976d..3e784405e 100644
--- a/tests/test_websupport.py
+++ b/tests/test_websupport.py
@@ -12,6 +12,8 @@
 import os
 from StringIO import StringIO
 
+from nose import SkipTest
+
 from sphinx.websupport import WebSupport
 from sphinx.websupport.errors import *
 from sphinx.websupport.storage.differ import CombinedHtmlDiff
@@ -79,10 +81,10 @@ def test_comments(support):
 
     # Create a displayed comment and a non displayed comment.
     comment = support.add_comment('First test comment',
-                                  node_id=str(first_node.id),
+                                  node_id=first_node.id,
                                   username='user_one')
     hidden_comment = support.add_comment('Hidden comment',
-                                         node_id=str(first_node.id),
+                                         node_id=first_node.id,
                                          displayed=False)
     # Make sure that comments can't be added to a comment where
     # displayed == False, since it could break the algorithm that
@@ -96,11 +98,11 @@ def test_comments(support):
                         parent_id=str(comment['id']), displayed=False)
     # Add a comment to another node to make sure it isn't returned later.
     support.add_comment('Second test comment',
-                        node_id=str(second_node.id),
+                        node_id=second_node.id,
                         username='user_two')
 
     # Access the comments as a moderator.
-    data = support.get_data(str(first_node.id), moderator=True)
+    data = support.get_data(first_node.id, moderator=True)
     comments = data['comments']
     children = comments[0]['children']
     assert len(comments) == 2
@@ -109,7 +111,7 @@ def test_comments(support):
     assert children[1]['text'] == 'Hidden child test comment'
 
     # Access the comments without being a moderator.
-    data = support.get_data(str(first_node.id))
+    data = support.get_data(first_node.id)
     comments = data['comments']
     children = comments[0]['children']
     assert len(comments) == 1
@@ -124,10 +126,10 @@ def test_voting(support):
     nodes = session.query(Node).all()
     node = nodes[0]
 
-    comment = support.get_data(str(node.id))['comments'][0]
+    comment = support.get_data(node.id)['comments'][0]
 
     def check_rating(val):
-        data = support.get_data(str(node.id))
+        data = support.get_data(node.id)
         comment = data['comments'][0]
         assert comment['rating'] == val, '%s != %s' % (comment['rating'], val)
 
@@ -156,13 +158,13 @@ def test_proposals(support):
     session = Session()
     node = session.query(Node).first()
 
-    data = support.get_data(str(node.id))
+    data = support.get_data(node.id)
 
     source = data['source']
     proposal = source[:5] + source[10:15] + 'asdf' + source[15:]
 
     comment = support.add_comment('Proposal comment',
-                                  node_id=str(node.id),
+                                  node_id=node.id,
                                   proposal=proposal)
 
 
@@ -172,7 +174,7 @@ def test_user_delete_comments(support):
         session = Session()
         node = session.query(Node).first()
         session.close()
-        return support.get_data(str(node.id))['comments'][0]
+        return support.get_data(node.id)['comments'][0]
 
     comment = get_comment()
     assert comment['username'] == 'user_one'
@@ -192,7 +194,7 @@ def test_moderator_delete_comments(support):
         session = Session()
         node = session.query(Node).first()
         session.close()
-        return support.get_data(str(node.id), moderator=True)['comments'][1]
+        return support.get_data(node.id, moderator=True)['comments'][1]
 
     comment = get_comment()
     support.delete_comment(comment['id'], username='user_two',
@@ -228,6 +230,8 @@ def moderation_callback(comment):
 
 @with_support(moderation_callback=moderation_callback)
 def test_moderation(support):
+    raise SkipTest(
+            'test is broken, relies on order of test execution and numeric ids')
     accepted = support.add_comment('Accepted Comment', node_id=3,
                                    displayed=False)
     rejected = support.add_comment('Rejected comment', node_id=3,

From ada394fe949ff246af428456754435fc10c26541 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Wed, 11 Aug 2010 18:15:30 +0200
Subject: [PATCH 111/127] Fixing indentation etc. Note: We need a javascript
 styleguide

---
 sphinx/themes/basic/static/websupport.js | 252 +++++++++++------------
 1 file changed, 123 insertions(+), 129 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 2e43c7324..5ee59b845 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -5,15 +5,13 @@
 
       $.fn.autogrow.resize(textarea);
 
-      $(textarea)
-	.focus(function() {
-	  textarea.interval = setInterval(function() {
-	    $.fn.autogrow.resize(textarea);
-	  }, 500);
-	})
-	.blur(function() {
-	  clearInterval(textarea.interval);
-	});
+      $(textarea).focus(function() {
+    	  textarea.interval = setInterval(function() {
+    	    $.fn.autogrow.resize(textarea);
+    	  }, 500);
+    	}).blur(function() {
+    	  clearInterval(textarea.interval);
+    	});
     });
   };
 
@@ -113,11 +111,11 @@
     if (document.cookie.length > 0) {
       var start = document.cookie.indexOf('sortBy=');
       if (start != -1) {
-	start = start + 7;
-	var end = document.cookie.indexOf(";", start);
-	if (end == -1)
-	  end = document.cookie.length;
-	by = unescape(document.cookie.substring(start, end));
+      	start = start + 7;
+      	var end = document.cookie.indexOf(";", start);
+      	if (end == -1)
+      	  end = document.cookie.length;
+        	by = unescape(document.cookie.substring(start, end));
       }
     }
     setComparator(by);
@@ -132,12 +130,12 @@
     // Reset the main comment form, and set the value of the parent input.
     $('form#comment_form')
       .find('textarea,input')
-	.removeAttr('disabled').end()
+    	.removeAttr('disabled').end()
       .find('input[name="node"]')
-	.val(id).end()
+    	.val(id).end()
       .find('textarea[name="proposal"]')
-	.val('')
-	.hide();
+    	.val('')
+    	.hide();
 
     // Position the popup and show it.
     var clientWidth = document.documentElement.clientWidth;
@@ -145,12 +143,12 @@
     $('div#focuser').fadeIn('fast');
     $('div.popup_comment')
       .css({
-	'top': 100+$(window).scrollTop(),
-	'left': clientWidth/2-popupWidth/2,
-	'position': 'absolute'
+      	'top': 100+$(window).scrollTop(),
+      	'left': clientWidth/2-popupWidth/2,
+      	'position': 'absolute'
       })
       .fadeIn('fast', function() {
-	getComments(id);
+      	getComments(id);
       });
   };
 
@@ -163,9 +161,9 @@
       $('ul#comment_ul').empty();
       $('h3#comment_notification').show();
       $('form#comment_form').find('textarea')
-	.val('').end()
-	.find('textarea, input')
-	  .removeAttr('disabled');
+      	.val('').end()
+      	.find('textarea, input')
+    	  .removeAttr('disabled');
     });
   };
 
@@ -179,28 +177,27 @@
       url: opts.getCommentsURL,
       data: {node: id},
       success: function(data, textStatus, request) {
-	var ul = $('ul#comment_ul').hide();
-	$('form#comment_form')
-	  .find('textarea[name="proposal"]')
-	    .data('source', data.source);
+      	var ul = $('ul#comment_ul').hide();
+      	$('form#comment_form')
+      	  .find('textarea[name="proposal"]')
+    	    .data('source', data.source);
 
-	if (data.comments.length == 0) {
-	  ul.html('<li>No comments yet.</li>');
-	  commentListEmpty = true;
-	  var speed = 100;
-	}
-	else {
-	  // If there are comments, sort them and put them in the list.
-	  var comments = sortComments(data.comments);
-	  var speed = data.comments.length * 100;
-	  appendComments(comments, ul);
-	  commentListEmpty = false;
-	}
-	$('h3#comment_notification').slideUp(speed+200);
-	ul.slideDown(speed);
+      	if (data.comments.length == 0) {
+      	  ul.html('<li>No comments yet.</li>');
+      	  commentListEmpty = true;
+      	  var speed = 100;
+      	}	else {
+      	  // If there are comments, sort them and put them in the list.
+      	  var comments = sortComments(data.comments);
+      	  var speed = data.comments.length * 100;
+      	  appendComments(comments, ul);
+      	  commentListEmpty = false;
+      	}
+      	$('h3#comment_notification').slideUp(speed+200);
+      	ul.slideDown(speed);
       },
       error: function(request, textStatus, error) {
-	showError('Oops, there was a problem retrieving the comments.');
+      	showError('Oops, there was a problem retrieving the comments.');
       },
       dataType: 'json'
     });
@@ -219,28 +216,30 @@
       type: "POST",
       url: opts.addCommentURL,
       dataType: 'json',
-      data: {node: node_id,
-             parent: form.find('input[name="parent"]').val(),
-	     text: form.find('textarea[name="comment"]').val(),
-	     proposal: form.find('textarea[name="proposal"]').val()},
+      data: {
+        node: node_id,
+        parent: form.find('input[name="parent"]').val(),
+        text: form.find('textarea[name="comment"]').val(),
+        proposal: form.find('textarea[name="proposal"]').val()
+      },
       success: function(data, textStatus, error) {
-	// Reset the form.
-	if (node_id) {
-	  hideProposeChange(node_id);
-	}
-	form.find('textarea')
-	  .val('')
-	    .add(form.find('input'))
+      	// Reset the form.
+      	if (node_id) {
+      	  hideProposeChange(node_id);
+      	}
+      	form.find('textarea')
+    	  .val('')
+	      .add(form.find('input'))
 	      .removeAttr('disabled');
-	if (commentListEmpty) {
-	  $('ul#comment_ul').empty();
-	  commentListEmpty = false;
-	}
-	insertComment(data.comment);
+      	if (commentListEmpty) {
+      	  $('ul#comment_ul').empty();
+      	  commentListEmpty = false;
+      	}
+      	insertComment(data.comment);
       },
       error: function(request, textStatus, error) {
-	form.find('textarea,input').removeAttr('disabled');
-	showError('Oops, there was a problem adding the comment.');
+      	form.find('textarea,input').removeAttr('disabled');
+      	showError('Oops, there was a problem adding the comment.');
       }
     });
   };
@@ -274,8 +273,7 @@
     if (comment.node != null) {
       var ul = $('ul#comment_ul');
       var siblings = getChildren(ul);
-    }
-    else {
+    } else {
       var ul = $('#cl' + comment.parent);
       var siblings = getChildren(ul);
     }
@@ -286,11 +284,11 @@
     // Determine where in the parents children list to insert this comment.
     for(i=0; i < siblings.length; i++) {
       if (comp(comment, siblings[i]) <= 0) {
-	$('#cd' + siblings[i].id)
-	  .parent()
-	    .before(li.html(div));
-	li.slideDown('fast');
-	return;
+      	$('#cd' + siblings[i].id)
+    	  .parent()
+	      .before(li.html(div));
+        li.slideDown('fast');
+      	return;
       }
     }
 
@@ -306,10 +304,10 @@
       url: opts.acceptCommentURL,
       data: {id: id},
       success: function(data, textStatus, request) {
-	$('#cm' + id).fadeOut('fast');
+      	$('#cm' + id).fadeOut('fast');
       },
       error: function(request, textStatus, error) {
-	showError("Oops, there was a problem accepting the comment.");
+      	showError("Oops, there was a problem accepting the comment.");
       },
     });
   };
@@ -320,13 +318,13 @@
       url: opts.rejectCommentURL,
       data: {id: id},
       success: function(data, textStatus, request) {
-	var div = $('#cd' + id);
-	div.slideUp('fast', function() {
-	  div.remove();
-	});
+      	var div = $('#cd' + id);
+      	div.slideUp('fast', function() {
+      	  div.remove();
+      	});
       },
       error: function(request, textStatus, error) {
-	showError("Oops, there was a problem rejecting the comment.");
+      	showError("Oops, there was a problem rejecting the comment.");
       },
     });
   };
@@ -337,22 +335,22 @@
       url: opts.deleteCommentURL,
       data: {id: id},
       success: function(data, textStatus, request) {
-	var div = $('#cd' + id);
-	div
-	  .find('span.user_id:first')
-	    .text('[deleted]').end()
-	  .find('p.comment_text:first')
-	    .text('[deleted]').end()
-	  .find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id +
-		', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id)
-	    .remove();
-	var comment = div.data('comment');
-	comment.username = '[deleted]';
-	comment.text = '[deleted]';
-	div.data('comment', comment);
+      	var div = $('#cd' + id);
+      	div
+    	    .find('span.user_id:first')
+  	      .text('[deleted]').end()
+      	  .find('p.comment_text:first')
+	        .text('[deleted]').end()
+      	  .find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id +
+		            ', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id)
+    	    .remove();
+      	var comment = div.data('comment');
+      	comment.username = '[deleted]';
+      	comment.text = '[deleted]';
+      	div.data('comment', comment);
       },
       error: function(request, textStatus, error) {
-	showError("Oops, there was a problem deleting the comment.");
+      	showError("Oops, there was a problem deleting the comment.");
       },
     });
   };
@@ -437,10 +435,8 @@
     // If this is not an unvote, and the other vote arrow has
     // already been pressed, unpress it.
     if ((d.value != 0) && (data.vote == d.value*-1)) {
-      $('#' + (d.value == 1 ? 'd' : 'u') + 'u' + d.comment_id)
-	.hide();
-      $('#' + (d.value == 1 ? 'd' : 'u') + 'v' + d.comment_id)
-	.show();
+      $('#' + (d.value == 1 ? 'd' : 'u') + 'u' + d.comment_id).hide();
+      $('#' + (d.value == 1 ? 'd' : 'u') + 'v' + d.comment_id).show();
     }
 
     // Update the comments rating in the local data.
@@ -458,7 +454,7 @@
       url: opts.processVoteURL,
       data: d,
       error: function(request, textStatus, error) {
-	showError("Oops, there was a problem casting that vote.");
+      	showError("Oops, there was a problem casting that vote.");
       }
     });
   };
@@ -477,12 +473,12 @@
       .prepend(div)
       // Setup the submit handler for the reply form.
       .find('#rf' + id)
-	.submit(function(event) {
-	  event.preventDefault();
-	  addComment($('#rf' + id));
-	  closeReply(id);
-	});
-    div.slideDown('fast');
+    	.submit(function(event) {
+    	  event.preventDefault();
+    	  addComment($('#rf' + id));
+    	  closeReply(id);
+    	});
+      div.slideDown('fast');
   };
 
   /**
@@ -520,10 +516,10 @@
     if (by.substring(0,3) == 'asc') {
       var i = by.substring(3);
       comp = function(a, b) { return a[i] - b[i]; }
-    }
-    // Otherwise sort in descending order.
-    else
+    } else {
+      // Otherwise sort in descending order.
       comp = function(a, b) { return b[by] - a[by]; }
+    }
 
     // Reset link styles and format the selected sort option.
     $('a.sel').attr('href', '#').removeClass('sel');
@@ -536,15 +532,14 @@
    */
   function getChildren(ul, recursive) {
     var children = [];
-    ul.children().children("[id^='cd']")
-      .each(function() {
-	var comment = $(this).data('comment');
-	if (recursive) {
-	  comment.children =
-	    getChildren($(this).find('#cl' + comment.id), true);
-	}
-	children.push(comment);
-      });
+    ul.children().children("[id^='cd']").each(function() {
+    	var comment = $(this).data('comment');
+    	if (recursive) {
+    	  comment.children =
+	        getChildren($(this).find('#cl' + comment.id), true);
+    	}
+    	children.push(comment);
+    });
     return children;
   };
 
@@ -569,16 +564,15 @@
     if (comment.text != '[deleted]') {
       div.find('a.reply').show();
       if (comment.proposal_diff) {
-	div.find('#sp' + comment.id).show();
+      	div.find('#sp' + comment.id).show();
       }
       if (opts.moderator && !comment.displayed) {
-	div.find('#cm' + comment.id).show();
+      	div.find('#cm' + comment.id).show();
       }
       if (opts.moderator || (opts.username == comment.username)) {
-	div.find('#dc' + comment.id).show();
+      	div.find('#dc' + comment.id).show();
       }
     }
-
     return div;
   }
 
@@ -592,7 +586,7 @@
     function handle(ph, escape) {
       var cur = context;
       $.each(ph.split('.'), function() {
-	cur = cur[this];
+      	cur = cur[this];
       });
       return escape ? esc.text(cur || "").html() : cur;
     }
@@ -606,10 +600,10 @@
     $('<div class="popup_error">' +
       '<h1>' + message + '</h1>' +
       '</div>')
-	.appendTo('body')
-	  .fadeIn("slow")
+    	.appendTo('body')
+   	  .fadeIn("slow")
 	    .delay(2000)
-	      .fadeOut("slow");
+      .fadeOut("slow");
   };
 
   /**
@@ -622,13 +616,13 @@
       var title = count + ' comment' + (count == 1 ? '' : 's');
       var image = count > 0 ? opts.commentBrightImage : opts.commentImage;
       $(this).append(
-	$('<a href="#" class="sphinx_comment"></a>')
-	  .html('<img src="' + image + '" alt="comment" />')
-	  .attr('title', title)
-	  .click(function(event) {
-	    event.preventDefault();
-	    show($(this).parent().attr('id'));
-	  }));
+      	$('<a href="#" class="sphinx_comment"></a>')
+      	  .html('<img src="' + image + '" alt="comment" />')
+      	  .attr('title', title)
+      	  .click(function(event) {
+      	    event.preventDefault();
+      	    show($(this).parent().attr('id'));
+      	  }));
     });
   };
 
@@ -759,4 +753,4 @@ $(document).ready(function() {
       result.highlightText(this.toLowerCase(), 'highlighted');
     });
   });
-});
\ No newline at end of file
+});

From 7e8fb7141b357ef6c1d726ad96b0e05f6db64be3 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 12 Aug 2010 14:41:25 -0500
Subject: [PATCH 112/127] allow commenting on literal_blocks

---
 sphinx/writers/websupport.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 05bc2c8b3..c6516bf17 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -15,7 +15,7 @@ class WebSupportTranslator(HTMLTranslator):
     """
     Our custom HTML translator.
     """
-    commentable_nodes = ['paragraph']
+    commentable_nodes = ['paragraph', 'literal_block']
 
     def __init__(self, builder, *args, **kwargs):
         HTMLTranslator.__init__(self, builder, *args, **kwargs)

From 5922d977392119d15f40963e8a5d7fe9ca368ade Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 12 Aug 2010 17:07:15 -0500
Subject: [PATCH 113/127] separate js templates from js scripts

---
 .../basic/static/websupport-templates.html    |  97 ++++++++++++++
 sphinx/themes/basic/static/websupport.js      | 123 ++++--------------
 sphinx/websupport/__init__.py                 |   3 +-
 3 files changed, 122 insertions(+), 101 deletions(-)
 create mode 100644 sphinx/themes/basic/static/websupport-templates.html

diff --git a/sphinx/themes/basic/static/websupport-templates.html b/sphinx/themes/basic/static/websupport-templates.html
new file mode 100644
index 000000000..1ea58ab24
--- /dev/null
+++ b/sphinx/themes/basic/static/websupport-templates.html
@@ -0,0 +1,97 @@
+<div id="templates">
+  <div id="reply_template">
+    <Li>
+      <div class="reply_div" id="rd<%id%>">
+	<form id="rf<%id%>">
+	  <textarea name="comment" cols="80"></textarea>
+          <input type="submit" value="add reply" />
+          <input type="hidden" name="parent" value="<%id%>" />
+          <input type="hidden" name="node" value="" />
+	</form>
+      </div>
+    </li>
+  </div>
+
+  <div id="comment_template">
+    <div  id="cd<%id%>" class="spxcdiv">
+      <div class="vote">
+	<div class="arrow">
+	  <a href="#" id="uv<%id%>" class="vote">
+	    <img src="<%upArrow%>" />
+	  </a>
+	  <a href="#" id="uu<%id%>" class="un vote">
+	    <img src="<%upArrowPressed%>" />
+	  </a>
+	</div>
+	<div class="arrow">
+	  <a href="#" id="dv<%id%>" class="vote">
+	    <img src="<%downArrow%>" id="da<%id%>" />
+	  </a>
+	  <a href="#" id="du<%id%>" class="un vote">
+	    <img src="<%downArrowPressed%>" />
+	  </a>
+	</div>
+      </div>
+      <div class="comment_content">
+	<p class="tagline comment">
+	  <span class="user_id"><%username%></span>
+	  <span class="rating"><%pretty_rating%></span>
+	  <span class="delta"><%time.delta%></span>
+	</p>
+	<p class="comment_text comment"><%text%></p>
+	<p class="comment_opts comment">
+	  <a href="#" class="reply hidden" id="rl<%id%>">reply &#9657;</a>
+	  <a href="#" class="close_reply" id="cr<%id%>">reply &#9663;</a>
+	  <a href="#" id="sp<%id%>" class="show_proposal">
+	    proposal &#9657;
+	  </a>
+	  <a href="#" id="hp<%id%>" class="hide_proposal">
+	    proposal &#9663;
+	  </a>
+	  <a href="#" id="dc<%id%>" class="delete_comment hidden">
+	    delete
+	  </a>
+	  <span id="cm<%id%>" class="moderation hidden">
+	    <a href="#" id="ac<%id%>" class="accept_comment">accept</a>
+	    <a href="#" id="rc<%id%>" class="reject_comment">reject</a>
+	  </span>
+	</p>
+	<pre class="proposal" id="pr<%id%>">
+	  <#proposal_diff#>
+	</pre>
+	<ul class="children" id="cl<%id%>"></ul>
+      </div>
+      <div class="clearleft"></div>
+    </div>
+  </div>
+
+  <div id="popup_template">
+    <div class="popup_comment">
+      <a id="comment_close" href="#">x</a>
+      <h1>Comments</h1>
+      <form method="post" id="comment_form" action="/docs/add_comment">
+	<textarea name="comment" cols="80"></textarea>
+	<p class="propose_button">
+	  <a href="#" class="show_propose_change">
+	    Propose a change &#9657;
+	  </a>
+	  <a href="#" class="hide_propose_change">
+	    Propose a change &#9663;
+	  </a>
+	</p>
+	<textarea name="proposal" cols="80" spellcheck="false"></textarea>
+	<input type="submit" value="add comment" id="comment_button" />
+	<input type="hidden" name="node" />
+	<input type="hidden" name="parent" value="" />
+	<p class="sort_options">
+	  Sort by:
+	  <a href="#" class="sort_option" id="rating">top</a>
+	  <a href="#" class="sort_option" id="ascage">newest</a>
+	  <a href="#" class="sort_option" id="age">oldest</a>
+	</p>
+      </form>
+      <h3 id="comment_notification">loading comments... <img src="<%loadingImage%>" alt="" /></h3>
+      <ul id="comment_ul"></ul>
+    </div>
+  </div>
+</div>
diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 2e43c7324..1f00ee465 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -31,11 +31,10 @@
 })(jQuery);
 
 (function($) {
-  var commentListEmpty, popup, comp;
+   var commentListEmpty, popup, comp, commentTemplate, replyTemplate;
 
   function init() {
     initTemplates();
-    initEvents();
     initComparator();
   };
 
@@ -95,12 +94,27 @@
   };
 
   function initTemplates() {
-    // Create our popup div, the same div is recycled each time comments
-    // are displayed.
-    popup = $(renderTemplate(popupTemplate, opts));
-    // Setup autogrow on the textareas
-    popup.find('textarea').autogrow();
-    $('body').append(popup);
+    var templateURL = opts.staticDir + '/_static/websupport-templates.html';
+    $.get(templateURL, function(data) {
+      var templates = $(data);
+      function loadTemplate(id) {
+	var html = templates.find('#' + id).html();
+	html = html.replace(/(&lt;)|(%3C)/g, "<");
+	html = html.replace(/(&gt;)|(%3E)/g, ">");
+        return html;
+      };
+      // Create our popup div, the same div is recycled each time comments
+      // are displayed.
+      // Setup autogrow on the textareas
+      var popupTemplate = loadTemplate('popup_template');
+      popup = $(renderTemplate(popupTemplate, opts));
+      popup.find('textarea').autogrow();
+
+      commentTemplate = loadTemplate('#comment_template');
+      replyTemplate = loadTemplate('#reply_template');
+      $('body').append(popup);
+      initEvents();
+    });
   };
 
   /**
@@ -646,102 +660,11 @@
     downArrow: '/static/_static/down.png',
     upArrowPressed: '/static/_static/up-pressed.png',
     downArrowPressed: '/static/_static/down-pressed.png',
+    staticDir: '/static',
     voting: false,
     moderator: false
   }, COMMENT_OPTIONS);
 
-  var replyTemplate = '    <li>\
-      <div class="reply_div" id="rd<%id%>">\
-	<form id="rf<%id%>">\
-	  <textarea name="comment" cols="80"></textarea>\
-          <input type="submit" value="add reply" />\
-          <input type="hidden" name="parent" value="<%id%>" />\
-          <input type="hidden" name="node" value="" />\
-        </form>\
-      </div>\
-    </li>';
-
-  var commentTemplate = '    <div  id="cd<%id%>" class="spxcdiv">\
-      <div class="vote">\
-	<div class="arrow">\
-	  <a href="#" id="uv<%id%>" class="vote">\
-	    <img src="<%upArrow%>" />\
-	  </a>\
-	  <a href="#" id="uu<%id%>" class="un vote">\
-	    <img src="<%upArrowPressed%>" />\
-	  </a>\
-	</div>\
-      <div class="arrow">\
-	  <a href="#" id="dv<%id%>" class="vote">\
-	    <img src="<%downArrow%>" id="da<%id%>" />\
-	  </a>\
-	  <a href="#" id="du<%id%>" class="un vote">\
-	    <img src="<%downArrowPressed%>" />\
-	  </a>\
-	</div>\
-      </div>\
-      <div class="comment_content">\
-	<p class="tagline comment">\
-	  <span class="user_id"><%username%></span>\
-	  <span class="rating"><%pretty_rating%></span>\
-	  <span class="delta"><%time.delta%></span>\
-	</p>\
-	<p class="comment_text comment"><%text%></p>\
-	<p class="comment_opts comment">\
-	  <a href="#" class="reply hidden" id="rl<%id%>">reply &#9657;</a>\
-	  <a href="#" class="close_reply" id="cr<%id%>">reply &#9663;</a>\
-	  <a href="#" id="sp<%id%>" class="show_proposal">\
-	    proposal &#9657;\
-	  </a>\
-	  <a href="#" id="hp<%id%>" class="hide_proposal">\
-	    proposal &#9663;\
-	  </a>\
-	  <a href="#" id="dc<%id%>" class="delete_comment hidden">\
-	    delete\
-	  </a>\
-	  <span id="cm<%id%>" class="moderation hidden">\
-	    <a href="#" id="ac<%id%>" class="accept_comment">accept</a>\
-	    <a href="#" id="rc<%id%>" class="reject_comment">reject</a>\
-	  </span>\
-	</p>\
-	<pre class="proposal" id="pr<%id%>">\
-<#proposal_diff#>\
-	</pre>\
-	<ul class="children" id="cl<%id%>"></ul>\
-      </div>\
-      <div class="clearleft"></div>\
-    </div>';
-
-   var popupTemplate = '    <div class="popup_comment">\
-      <a id="comment_close" href="#">x</a>\
-      <h1>Comments</h1>\
-      <form method="post" id="comment_form" action="/docs/add_comment">\
-	<textarea name="comment" cols="80"></textarea>\
-	<p class="propose_button">\
-	  <a href="#" class="show_propose_change">\
-	    Propose a change &#9657;\
-	  </a>\
-	  <a href="#" class="hide_propose_change">\
-	    Propose a change &#9663;\
-	  </a>\
-	</p>\
-	<textarea name="proposal" cols="80" spellcheck="false"></textarea>\
-	<input type="submit" value="add comment" id="comment_button" />\
-	<input type="hidden" name="node" />\
-	<input type="hidden" name="parent" value="" />\
-      <p class="sort_options">\
-	Sort by:\
-	<a href="#" class="sort_option" id="rating">top</a>\
-	<a href="#" class="sort_option" id="ascage">newest</a>\
-	<a href="#" class="sort_option" id="age">oldest</a>\
-      </p>\
-      </form>\
-      <h3 id="comment_notification">loading comments... <img src="' +
-      opts.loadingImage + '" alt="" /></h3>\
-      <ul id="comment_ul"></ul>\
-    </div>\
-    <div id="focuser"></div>';
-
   $(document).ready(function() {
     init();
   });
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index cc065b7f7..939428a6c 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -376,7 +376,8 @@ class WebSupport(object):
                 ('upArrow', 'up.png'),
                 ('upArrowPressed', 'up-pressed.png'),
                 ('downArrow', 'down.png'),
-                ('downArrowPressed', 'down-pressed.png')
+                ('downArrowPressed', 'down-pressed.png'),
+                ('staticDir', '/' + self.staticdir)
             ]
             for key, value in static_urls:
                 self.base_comment_opts[key] = \

From 4dc41e52939907558f881b4aa40fd822315aa6de Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Thu, 12 Aug 2010 17:08:27 -0500
Subject: [PATCH 114/127] remove modal focuser

---
 sphinx/themes/basic/static/websupport.js | 2 --
 1 file changed, 2 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 1f00ee465..80c6a9a5b 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -156,7 +156,6 @@
     // Position the popup and show it.
     var clientWidth = document.documentElement.clientWidth;
     var popupWidth = $('div.popup_comment').width();
-    $('div#focuser').fadeIn('fast');
     $('div.popup_comment')
       .css({
 	'top': 100+$(window).scrollTop(),
@@ -172,7 +171,6 @@
    * Hide the comments popup window.
    */
   function hide() {
-    $('div#focuser').fadeOut('fast');
     $('div.popup_comment').fadeOut('fast', function() {
       $('ul#comment_ul').empty();
       $('h3#comment_notification').show();

From 305977359d5a210c136d2ef638fb1365384bd187 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Fri, 13 Aug 2010 11:37:21 +0200
Subject: [PATCH 115/127] Fix indentation

---
 .../basic/static/websupport-templates.html    | 132 +++++++++---------
 1 file changed, 66 insertions(+), 66 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport-templates.html b/sphinx/themes/basic/static/websupport-templates.html
index 1ea58ab24..9e7c06690 100644
--- a/sphinx/themes/basic/static/websupport-templates.html
+++ b/sphinx/themes/basic/static/websupport-templates.html
@@ -1,13 +1,13 @@
 <div id="templates">
   <div id="reply_template">
-    <Li>
+    <li>
       <div class="reply_div" id="rd<%id%>">
-	<form id="rf<%id%>">
-	  <textarea name="comment" cols="80"></textarea>
+        <form id="rf<%id%>">
+          <textarea name="comment" cols="80"></textarea>
           <input type="submit" value="add reply" />
           <input type="hidden" name="parent" value="<%id%>" />
           <input type="hidden" name="node" value="" />
-	</form>
+        </form>
       </div>
     </li>
   </div>
@@ -15,51 +15,51 @@
   <div id="comment_template">
     <div  id="cd<%id%>" class="spxcdiv">
       <div class="vote">
-	<div class="arrow">
-	  <a href="#" id="uv<%id%>" class="vote">
-	    <img src="<%upArrow%>" />
-	  </a>
-	  <a href="#" id="uu<%id%>" class="un vote">
-	    <img src="<%upArrowPressed%>" />
-	  </a>
-	</div>
-	<div class="arrow">
-	  <a href="#" id="dv<%id%>" class="vote">
-	    <img src="<%downArrow%>" id="da<%id%>" />
-	  </a>
-	  <a href="#" id="du<%id%>" class="un vote">
-	    <img src="<%downArrowPressed%>" />
-	  </a>
-	</div>
+        <div class="arrow">
+          <a href="#" id="uv<%id%>" class="vote">
+            <img src="<%upArrow%>" />
+          </a>
+          <a href="#" id="uu<%id%>" class="un vote">
+            <img src="<%upArrowPressed%>" />
+          </a>
+        </div>
+        <div class="arrow">
+          <a href="#" id="dv<%id%>" class="vote">
+            <img src="<%downArrow%>" id="da<%id%>" />
+          </a>
+          <a href="#" id="du<%id%>" class="un vote">
+            <img src="<%downArrowPressed%>" />
+          </a>
+        </div>
       </div>
       <div class="comment_content">
-	<p class="tagline comment">
-	  <span class="user_id"><%username%></span>
-	  <span class="rating"><%pretty_rating%></span>
-	  <span class="delta"><%time.delta%></span>
-	</p>
-	<p class="comment_text comment"><%text%></p>
-	<p class="comment_opts comment">
-	  <a href="#" class="reply hidden" id="rl<%id%>">reply &#9657;</a>
-	  <a href="#" class="close_reply" id="cr<%id%>">reply &#9663;</a>
-	  <a href="#" id="sp<%id%>" class="show_proposal">
-	    proposal &#9657;
-	  </a>
-	  <a href="#" id="hp<%id%>" class="hide_proposal">
-	    proposal &#9663;
-	  </a>
-	  <a href="#" id="dc<%id%>" class="delete_comment hidden">
-	    delete
-	  </a>
-	  <span id="cm<%id%>" class="moderation hidden">
-	    <a href="#" id="ac<%id%>" class="accept_comment">accept</a>
-	    <a href="#" id="rc<%id%>" class="reject_comment">reject</a>
-	  </span>
-	</p>
-	<pre class="proposal" id="pr<%id%>">
-	  <#proposal_diff#>
-	</pre>
-	<ul class="children" id="cl<%id%>"></ul>
+        <p class="tagline comment">
+          <span class="user_id"><%username%></span>
+          <span class="rating"><%pretty_rating%></span>
+          <span class="delta"><%time.delta%></span>
+        </p>
+        <p class="comment_text comment"><%text%></p>
+        <p class="comment_opts comment">
+          <a href="#" class="reply hidden" id="rl<%id%>">reply &#9657;</a>
+          <a href="#" class="close_reply" id="cr<%id%>">reply &#9663;</a>
+          <a href="#" id="sp<%id%>" class="show_proposal">
+            proposal &#9657;
+          </a>
+          <a href="#" id="hp<%id%>" class="hide_proposal">
+            proposal &#9663;
+          </a>
+          <a href="#" id="dc<%id%>" class="delete_comment hidden">
+            delete
+          </a>
+          <span id="cm<%id%>" class="moderation hidden">
+            <a href="#" id="ac<%id%>" class="accept_comment">accept</a>
+            <a href="#" id="rc<%id%>" class="reject_comment">reject</a>
+          </span>
+        </p>
+        <pre class="proposal" id="pr<%id%>">
+          <#proposal_diff#>
+        </pre>
+        <ul class="children" id="cl<%id%>"></ul>
       </div>
       <div class="clearleft"></div>
     </div>
@@ -70,25 +70,25 @@
       <a id="comment_close" href="#">x</a>
       <h1>Comments</h1>
       <form method="post" id="comment_form" action="/docs/add_comment">
-	<textarea name="comment" cols="80"></textarea>
-	<p class="propose_button">
-	  <a href="#" class="show_propose_change">
-	    Propose a change &#9657;
-	  </a>
-	  <a href="#" class="hide_propose_change">
-	    Propose a change &#9663;
-	  </a>
-	</p>
-	<textarea name="proposal" cols="80" spellcheck="false"></textarea>
-	<input type="submit" value="add comment" id="comment_button" />
-	<input type="hidden" name="node" />
-	<input type="hidden" name="parent" value="" />
-	<p class="sort_options">
-	  Sort by:
-	  <a href="#" class="sort_option" id="rating">top</a>
-	  <a href="#" class="sort_option" id="ascage">newest</a>
-	  <a href="#" class="sort_option" id="age">oldest</a>
-	</p>
+        <textarea name="comment" cols="80"></textarea>
+        <p class="propose_button">
+          <a href="#" class="show_propose_change">
+            Propose a change &#9657;
+          </a>
+          <a href="#" class="hide_propose_change">
+            Propose a change &#9663;
+          </a>
+        </p>
+        <textarea name="proposal" cols="80" spellcheck="false"></textarea>
+        <input type="submit" value="add comment" id="comment_button" />
+        <input type="hidden" name="node" />
+        <input type="hidden" name="parent" value="" />
+        <p class="sort_options">
+          Sort by:
+          <a href="#" class="sort_option" id="rating">top</a>
+          <a href="#" class="sort_option" id="ascage">newest</a>
+          <a href="#" class="sort_option" id="age">oldest</a>
+        </p>
       </form>
       <h3 id="comment_notification">loading comments... <img src="<%loadingImage%>" alt="" /></h3>
       <ul id="comment_ul"></ul>

From 134010e35734b986aa442a9e5047e5811dd1afa5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Fri, 13 Aug 2010 11:44:09 +0200
Subject: [PATCH 116/127] Put literal_blocks under versioning

---
 sphinx/builders/websupport.py |  7 +++----
 sphinx/util/websupport.py     | 10 ++++++++++
 sphinx/writers/websupport.py  |  6 +++---
 3 files changed, 16 insertions(+), 7 deletions(-)
 create mode 100644 sphinx/util/websupport.py

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index e1bd80111..2e05da5be 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -22,13 +22,12 @@ from docutils.utils import Reporter
 
 from sphinx.util.osutil import os_path, relative_uri, ensuredir, copyfile
 from sphinx.util.jsonimpl import dumps as dump_json
+from sphinx.util.websupport import is_commentable
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.writers.websupport import WebSupportTranslator
 from sphinx.environment import WarningStream
 from sphinx.versioning import add_uids, merge_doctrees
 
-def is_paragraph(node):
-    return node.__class__.__name__ == 'paragraph'
 
 class WebSupportBuilder(StandaloneHTMLBuilder):
     """
@@ -66,9 +65,9 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
 
         old_doctree = self.get_old_doctree(docname)
         if old_doctree:
-            list(merge_doctrees(old_doctree, doctree, is_paragraph))
+            list(merge_doctrees(old_doctree, doctree, is_commentable))
         else:
-            list(add_uids(doctree, is_paragraph))
+            list(add_uids(doctree, is_commentable))
 
         self.cur_docname = docname
         self.secnumbers = self.env.toc_secnumbers.get(docname, {})
diff --git a/sphinx/util/websupport.py b/sphinx/util/websupport.py
new file mode 100644
index 000000000..f99f4d31d
--- /dev/null
+++ b/sphinx/util/websupport.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.util.websupport
+    ~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+def is_commentable(node):
+    return node.__class__.__name__ in ('paragraph', 'literal_block')
diff --git a/sphinx/writers/websupport.py b/sphinx/writers/websupport.py
index 84af925ed..fbd3c1ef5 100644
--- a/sphinx/writers/websupport.py
+++ b/sphinx/writers/websupport.py
@@ -10,12 +10,12 @@
 """
 
 from sphinx.writers.html import HTMLTranslator
+from sphinx.util.websupport import is_commentable
 
 class WebSupportTranslator(HTMLTranslator):
     """
     Our custom HTML translator.
     """
-    commentable_nodes = ['paragraph', 'literal_block']
 
     def __init__(self, builder, *args, **kwargs):
         HTMLTranslator.__init__(self, builder, *args, **kwargs)
@@ -26,13 +26,13 @@ class WebSupportTranslator(HTMLTranslator):
         self.cur_node = None
 
     def dispatch_visit(self, node):
-        if node.__class__.__name__ in self.commentable_nodes:
+        if is_commentable(node):
             self.handle_visit_commentable(node)
         HTMLTranslator.dispatch_visit(self, node)
 
     def dispatch_departure(self, node):
         HTMLTranslator.dispatch_departure(self, node)
-        if node.__class__.__name__ in self.commentable_nodes:
+        if is_commentable(node):
             self.handle_depart_commentable(node)
 
     def handle_visit_commentable(self, node):

From 1509c0d3d353c72591f2ff5997c00f98d1b71555 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Fri, 13 Aug 2010 15:10:48 +0200
Subject: [PATCH 117/127] Use a more consistent style in the websupport js

---
 sphinx/themes/basic/static/websupport.js | 409 ++++++++++++-----------
 1 file changed, 205 insertions(+), 204 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 80c6a9a5b..863a57a5a 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -1,19 +1,19 @@
 (function($) {
   $.fn.autogrow = function(){
     return this.each(function(){
-      var textarea = this;
+    var textarea = this;
 
-      $.fn.autogrow.resize(textarea);
+    $.fn.autogrow.resize(textarea);
 
-      $(textarea)
-	.focus(function() {
-	  textarea.interval = setInterval(function() {
-	    $.fn.autogrow.resize(textarea);
-	  }, 500);
-	})
-	.blur(function() {
-	  clearInterval(textarea.interval);
-	});
+    $(textarea)
+      .focus(function() {
+        textarea.interval = setInterval(function() {
+          $.fn.autogrow.resize(textarea);
+        }, 500);
+      })
+      .blur(function() {
+        clearInterval(textarea.interval);
+      });
     });
   };
 
@@ -31,7 +31,7 @@
 })(jQuery);
 
 (function($) {
-   var commentListEmpty, popup, comp, commentTemplate, replyTemplate;
+  var commentListEmpty, popup, comp, commentTemplate, replyTemplate;
 
   function init() {
     initTemplates();
@@ -98,9 +98,9 @@
     $.get(templateURL, function(data) {
       var templates = $(data);
       function loadTemplate(id) {
-	var html = templates.find('#' + id).html();
-	html = html.replace(/(&lt;)|(%3C)/g, "<");
-	html = html.replace(/(&gt;)|(%3E)/g, ">");
+        var html = templates.find('#' + id).html();
+        html = html.replace(/(&lt;)|(%3C)/g, "<");
+        html = html.replace(/(&gt;)|(%3E)/g, ">");
         return html;
       };
       // Create our popup div, the same div is recycled each time comments
@@ -117,110 +117,109 @@
     });
   };
 
-  /**
-   * Create a comp function. If the user has preferences stored in
-   * the sortBy cookie, use those, otherwise use the default.
-   */
+  /*
+   Create a comp function. If the user has preferences stored in
+   the sortBy cookie, use those, otherwise use the default.
+  */
   function initComparator() {
     var by = 'rating'; // Default to sort by rating.
     // If the sortBy cookie is set, use that instead.
     if (document.cookie.length > 0) {
       var start = document.cookie.indexOf('sortBy=');
       if (start != -1) {
-	start = start + 7;
-	var end = document.cookie.indexOf(";", start);
-	if (end == -1)
-	  end = document.cookie.length;
-	by = unescape(document.cookie.substring(start, end));
-      }
+        start = start + 7;
+        var end = document.cookie.indexOf(";", start);
+        if (end == -1)
+          end = document.cookie.length;
+          by = unescape(document.cookie.substring(start, end));
+        }
     }
     setComparator(by);
   };
 
-  /**
-   * Show the comments popup window.
-   */
+  /*
+   Show the comments popup window.
+  */
   function show(nodeId) {
     var id = nodeId.substring(1);
 
     // Reset the main comment form, and set the value of the parent input.
     $('form#comment_form')
       .find('textarea,input')
-	.removeAttr('disabled').end()
+      .removeAttr('disabled').end()
       .find('input[name="node"]')
-	.val(id).end()
+      .val(id).end()
       .find('textarea[name="proposal"]')
-	.val('')
-	.hide();
+      .val('')
+      .hide();
 
     // Position the popup and show it.
     var clientWidth = document.documentElement.clientWidth;
     var popupWidth = $('div.popup_comment').width();
     $('div.popup_comment')
       .css({
-	'top': 100+$(window).scrollTop(),
-	'left': clientWidth/2-popupWidth/2,
-	'position': 'absolute'
+        'top': 100+$(window).scrollTop(),
+        'left': clientWidth/2-popupWidth/2,
+        'position': 'absolute'
       })
       .fadeIn('fast', function() {
-	getComments(id);
+        getComments(id);
       });
   };
 
-  /**
-   * Hide the comments popup window.
-   */
+  /*
+   Hide the comments popup window.
+  */
   function hide() {
     $('div.popup_comment').fadeOut('fast', function() {
       $('ul#comment_ul').empty();
       $('h3#comment_notification').show();
       $('form#comment_form').find('textarea')
-	.val('').end()
-	.find('textarea, input')
-	  .removeAttr('disabled');
+        .val('').end()
+        .find('textarea, input')
+        .removeAttr('disabled');
     });
   };
 
-  /**
-   * Perform an ajax request to get comments for a node
-   * and insert the comments into the comments tree.
-   */
+  /*
+   Perform an ajax request to get comments for a node
+   and insert the comments into the comments tree.
+  */
   function getComments(id) {
     $.ajax({
-      type: 'GET',
-      url: opts.getCommentsURL,
-      data: {node: id},
-      success: function(data, textStatus, request) {
-	var ul = $('ul#comment_ul').hide();
-	$('form#comment_form')
-	  .find('textarea[name="proposal"]')
-	    .data('source', data.source);
+     type: 'GET',
+     url: opts.getCommentsURL,
+     data: {node: id},
+     success: function(data, textStatus, request) {
+       var ul = $('ul#comment_ul').hide();
+       $('form#comment_form')
+         .find('textarea[name="proposal"]')
+         .data('source', data.source);
 
-	if (data.comments.length == 0) {
-	  ul.html('<li>No comments yet.</li>');
-	  commentListEmpty = true;
-	  var speed = 100;
-	}
-	else {
-	  // If there are comments, sort them and put them in the list.
-	  var comments = sortComments(data.comments);
-	  var speed = data.comments.length * 100;
-	  appendComments(comments, ul);
-	  commentListEmpty = false;
-	}
-	$('h3#comment_notification').slideUp(speed+200);
-	ul.slideDown(speed);
-      },
-      error: function(request, textStatus, error) {
-	showError('Oops, there was a problem retrieving the comments.');
-      },
-      dataType: 'json'
+       if (data.comments.length == 0) {
+         ul.html('<li>No comments yet.</li>');
+         commentListEmpty = true;
+         var speed = 100;
+       } else {
+         // If there are comments, sort them and put them in the list.
+         var comments = sortComments(data.comments);
+         var speed = data.comments.length * 100;
+         appendComments(comments, ul);
+         commentListEmpty = false;
+       }
+       $('h3#comment_notification').slideUp(speed+200);
+       ul.slideDown(speed);
+     },
+     error: function(request, textStatus, error) {
+       showError('Oops, there was a problem retrieving the comments.');
+     },
+     dataType: 'json'
     });
   };
 
-  /**
-   * Add a comment via ajax and insert the comment into the comment tree.
-   */
+  /*
+   Add a comment via ajax and insert the comment into the comment tree.
+  */
   function addComment(form) {
     // Disable the form that is being submitted.
     form.find('textarea,input').attr('disabled', 'disabled');
@@ -231,36 +230,38 @@
       type: "POST",
       url: opts.addCommentURL,
       dataType: 'json',
-      data: {node: node_id,
-             parent: form.find('input[name="parent"]').val(),
-	     text: form.find('textarea[name="comment"]').val(),
-	     proposal: form.find('textarea[name="proposal"]').val()},
+      data: {
+        node: node_id,
+        parent: form.find('input[name="parent"]').val(),
+        text: form.find('textarea[name="comment"]').val(),
+        proposal: form.find('textarea[name="proposal"]').val()
+      },
       success: function(data, textStatus, error) {
-	// Reset the form.
-	if (node_id) {
-	  hideProposeChange(node_id);
-	}
-	form.find('textarea')
-	  .val('')
-	    .add(form.find('input'))
-	      .removeAttr('disabled');
-	if (commentListEmpty) {
-	  $('ul#comment_ul').empty();
-	  commentListEmpty = false;
-	}
-	insertComment(data.comment);
+        // Reset the form.
+        if (node_id) {
+          hideProposeChange(node_id);
+        }
+        form.find('textarea')
+          .val('')
+          .add(form.find('input'))
+          .removeAttr('disabled');
+        if (commentListEmpty) {
+          $('ul#comment_ul').empty();
+          commentListEmpty = false;
+        }
+        insertComment(data.comment);
       },
       error: function(request, textStatus, error) {
-	form.find('textarea,input').removeAttr('disabled');
-	showError('Oops, there was a problem adding the comment.');
+        form.find('textarea,input').removeAttr('disabled');
+        showError('Oops, there was a problem adding the comment.');
       }
     });
   };
 
-  /**
-   * Recursively append comments to the main comment list and children
-   * lists, creating the comment tree.
-   */
+  /*
+   Recursively append comments to the main comment list and children
+   lists, creating the comment tree.
+  */
   function appendComments(comments, ul) {
     $.each(comments, function() {
       var div = createCommentDiv(this);
@@ -272,10 +273,10 @@
     });
   };
 
-  /**
-   * After adding a new comment, it must be inserted in the correct
-   * location in the comment tree.
-   */
+  /*
+   After adding a new comment, it must be inserted in the correct
+   location in the comment tree.
+  */
   function insertComment(comment) {
     var div = createCommentDiv(comment);
 
@@ -286,8 +287,7 @@
     if (comment.node != null) {
       var ul = $('ul#comment_ul');
       var siblings = getChildren(ul);
-    }
-    else {
+    } else {
       var ul = $('#cl' + comment.parent);
       var siblings = getChildren(ul);
     }
@@ -298,11 +298,11 @@
     // Determine where in the parents children list to insert this comment.
     for(i=0; i < siblings.length; i++) {
       if (comp(comment, siblings[i]) <= 0) {
-	$('#cd' + siblings[i].id)
-	  .parent()
-	    .before(li.html(div));
-	li.slideDown('fast');
-	return;
+        $('#cd' + siblings[i].id)
+          .parent()
+          .before(li.html(div));
+        li.slideDown('fast');
+        return;
       }
     }
 
@@ -318,10 +318,10 @@
       url: opts.acceptCommentURL,
       data: {id: id},
       success: function(data, textStatus, request) {
-	$('#cm' + id).fadeOut('fast');
+        $('#cm' + id).fadeOut('fast');
       },
       error: function(request, textStatus, error) {
-	showError("Oops, there was a problem accepting the comment.");
+        showError("Oops, there was a problem accepting the comment.");
       },
     });
   };
@@ -332,13 +332,13 @@
       url: opts.rejectCommentURL,
       data: {id: id},
       success: function(data, textStatus, request) {
-	var div = $('#cd' + id);
-	div.slideUp('fast', function() {
-	  div.remove();
-	});
+        var div = $('#cd' + id);
+        div.slideUp('fast', function() {
+        div.remove();
+        });
       },
       error: function(request, textStatus, error) {
-	showError("Oops, there was a problem rejecting the comment.");
+        showError("Oops, there was a problem rejecting the comment.");
       },
     });
   };
@@ -349,22 +349,22 @@
       url: opts.deleteCommentURL,
       data: {id: id},
       success: function(data, textStatus, request) {
-	var div = $('#cd' + id);
-	div
-	  .find('span.user_id:first')
-	    .text('[deleted]').end()
-	  .find('p.comment_text:first')
-	    .text('[deleted]').end()
-	  .find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id +
-		', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id)
-	    .remove();
-	var comment = div.data('comment');
-	comment.username = '[deleted]';
-	comment.text = '[deleted]';
-	div.data('comment', comment);
+        var div = $('#cd' + id);
+        div
+          .find('span.user_id:first')
+          .text('[deleted]').end()
+          .find('p.comment_text:first')
+          .text('[deleted]').end()
+          .find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id +
+                ', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id)
+          .remove();
+        var comment = div.data('comment');
+        comment.username = '[deleted]';
+        comment.text = '[deleted]';
+        div.data('comment', comment);
       },
       error: function(request, textStatus, error) {
-	showError("Oops, there was a problem deleting the comment.");
+        showError("Oops, there was a problem deleting the comment.");
       },
     });
   };
@@ -398,25 +398,25 @@
     textarea.slideUp('fast');
   };
 
-  /**
-   * Handle when the user clicks on a sort by link.
-   */
+  /*
+   Handle when the user clicks on a sort by link.
+  */
   function handleReSort(link) {
     setComparator(link.attr('id'));
-     // Save/update the sortBy cookie.
+    // Save/update the sortBy cookie.
     var expiration = new Date();
     expiration.setDate(expiration.getDate() + 365);
     document.cookie= 'sortBy=' + escape(link.attr('id')) +
-      ';expires=' + expiration.toUTCString();
+                     ';expires=' + expiration.toUTCString();
     var comments = getChildren($('ul#comment_ul'), true);
     comments = sortComments(comments);
 
     appendComments(comments, $('ul#comment_ul').empty());
   };
 
-  /**
-   * Function to process a vote when a user clicks an arrow.
-   */
+  /*
+   Function to process a vote when a user clicks an arrow.
+  */
   function handleVote(link) {
     if (!opts.voting) {
       showError("You'll need to login to vote.");
@@ -426,11 +426,11 @@
     var id = link.attr('id');
     // If it is an unvote, the new vote value is 0,
     // Otherwise it's 1 for an upvote, or -1 for a downvote.
-    if (id.charAt(1) == 'u')
+    if (id.charAt(1) == 'u') {
       var value = 0;
-    else
+    } else {
       var value = id.charAt(0) == 'u' ? 1 : -1;
-
+    }
     // The data to be sent to the server.
     var d = {
       comment_id: id.substring(2),
@@ -450,9 +450,9 @@
     // already been pressed, unpress it.
     if ((d.value != 0) && (data.vote == d.value*-1)) {
       $('#' + (d.value == 1 ? 'd' : 'u') + 'u' + d.comment_id)
-	.hide();
+        .hide();
       $('#' + (d.value == 1 ? 'd' : 'u') + 'v' + d.comment_id)
-	.show();
+        .show();
     }
 
     // Update the comments rating in the local data.
@@ -470,14 +470,14 @@
       url: opts.processVoteURL,
       data: d,
       error: function(request, textStatus, error) {
-	showError("Oops, there was a problem casting that vote.");
+        showError("Oops, there was a problem casting that vote.");
       }
     });
   };
 
-  /**
-   * Open a reply form used to reply to an existing comment.
-   */
+  /*
+   Open a reply form used to reply to an existing comment.
+  */
   function openReply(id) {
     // Swap out the reply link for the hide link
     $('#rl' + id).hide();
@@ -489,17 +489,17 @@
       .prepend(div)
       // Setup the submit handler for the reply form.
       .find('#rf' + id)
-	.submit(function(event) {
-	  event.preventDefault();
-	  addComment($('#rf' + id));
-	  closeReply(id);
-	});
+      .submit(function(event) {
+        event.preventDefault();
+        addComment($('#rf' + id));
+        closeReply(id);
+      });
     div.slideDown('fast');
   };
 
-  /**
-   * Close the reply form opened with openReply.
-   */
+  /*
+   Close the reply form opened with openReply.
+  */
   function closeReply(id) {
     // Remove the reply div from the DOM.
     $('#rd' + id).slideUp('fast', function() {
@@ -511,9 +511,9 @@
     $('#rl' + id).show();
   };
 
-  /**
-   * Recursively sort a tree of comments using the comp comparator.
-   */
+  /*
+   Recursively sort a tree of comments using the comp comparator.
+  */
   function sortComments(comments) {
     comments.sort(comp);
     $.each(comments, function() {
@@ -522,51 +522,50 @@
     return comments;
   };
 
-  /**
-   * Set comp, which is a comparator function used for sorting and
-   * inserting comments into the list.
-   */
+  /*
+   Set comp, which is a comparator function used for sorting and
+   inserting comments into the list.
+  */
   function setComparator(by) {
     // If the first three letters are "asc", sort in ascending order
     // and remove the prefix.
     if (by.substring(0,3) == 'asc') {
       var i = by.substring(3);
       comp = function(a, b) { return a[i] - b[i]; }
-    }
-    // Otherwise sort in descending order.
-    else
+    } else {
+      // Otherwise sort in descending order.
       comp = function(a, b) { return b[by] - a[by]; }
+    }
 
     // Reset link styles and format the selected sort option.
     $('a.sel').attr('href', '#').removeClass('sel');
     $('#' + by).removeAttr('href').addClass('sel');
   };
 
-  /**
-   * Get the children comments from a ul. If recursive is true,
-   * recursively include childrens' children.
-   */
+  /*
+   Get the children comments from a ul. If recursive is true,
+   recursively include childrens' children.
+  */
   function getChildren(ul, recursive) {
     var children = [];
     ul.children().children("[id^='cd']")
       .each(function() {
-	var comment = $(this).data('comment');
-	if (recursive) {
-	  comment.children =
-	    getChildren($(this).find('#cl' + comment.id), true);
-	}
-	children.push(comment);
+        var comment = $(this).data('comment');
+        if (recursive) {
+          comment.children = getChildren($(this).find('#cl' + comment.id), true);
+        }
+        children.push(comment);
       });
     return children;
   };
 
-  /**
-   * Create a div to display a comment in.
-   */
+  /*
+   Create a div to display a comment in.
+  */
   function createCommentDiv(comment) {
     // Prettify the comment rating.
     comment.pretty_rating = comment.rating + ' point' +
-      (comment.rating == 1 ? '' : 's');
+    (comment.rating == 1 ? '' : 's');
     // Create a div for this comment.
     var context = $.extend({}, opts, comment);
     var div = $(renderTemplate(commentTemplate, context));
@@ -581,30 +580,30 @@
     if (comment.text != '[deleted]') {
       div.find('a.reply').show();
       if (comment.proposal_diff) {
-	div.find('#sp' + comment.id).show();
+        div.find('#sp' + comment.id).show();
       }
       if (opts.moderator && !comment.displayed) {
-	div.find('#cm' + comment.id).show();
+        div.find('#cm' + comment.id).show();
       }
       if (opts.moderator || (opts.username == comment.username)) {
-	div.find('#dc' + comment.id).show();
+        div.find('#dc' + comment.id).show();
       }
     }
 
     return div;
   }
 
-  /**
-   * A simple template renderer. Placeholders such as <%id%> are replaced
-   * by context['id']. Items are always escaped.
-   */
+  /*
+   A simple template renderer. Placeholders such as <%id%> are replaced
+   by context['id']. Items are always escaped.
+  */
   function renderTemplate(template, context) {
     var esc = $('<span></span>');
 
     function handle(ph, escape) {
       var cur = context;
       $.each(ph.split('.'), function() {
-	cur = cur[this];
+        cur = cur[this];
       });
       return escape ? esc.text(cur || "").html() : cur;
     }
@@ -617,16 +616,17 @@
   function showError(message) {
     $('<div class="popup_error">' +
       '<h1>' + message + '</h1>' +
-      '</div>')
-	.appendTo('body')
-	  .fadeIn("slow")
-	    .delay(2000)
-	      .fadeOut("slow");
+      '</div>'
+    )
+      .appendTo('body')
+      .fadeIn("slow")
+      .delay(2000)
+      .fadeOut("slow");
   };
 
-  /**
-   * Add a link the user uses to open the comments popup.
-   */
+  /*
+   Add a link the user uses to open the comments popup.
+  */
   $.fn.comment = function() {
     return this.each(function() {
       var id = $(this).attr('id').substring(1);
@@ -634,13 +634,14 @@
       var title = count + ' comment' + (count == 1 ? '' : 's');
       var image = count > 0 ? opts.commentBrightImage : opts.commentImage;
       $(this).append(
-	$('<a href="#" class="sphinx_comment"></a>')
-	  .html('<img src="' + image + '" alt="comment" />')
-	  .attr('title', title)
-	  .click(function(event) {
-	    event.preventDefault();
-	    show($(this).parent().attr('id'));
-	  }));
+        $('<a href="#" class="sphinx_comment"></a>')
+          .html('<img src="' + image + '" alt="comment" />')
+          .attr('title', title)
+          .click(function(event) {
+            event.preventDefault();
+            show($(this).parent().attr('id'));
+          })
+      );
     });
   };
 
@@ -680,4 +681,4 @@ $(document).ready(function() {
       result.highlightText(this.toLowerCase(), 'highlighted');
     });
   });
-});
\ No newline at end of file
+});

From 1fa4c78c38a0ed5cc983edfa1132cd65101614ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Fri, 13 Aug 2010 16:26:46 +0200
Subject: [PATCH 118/127] Put spaces around operators

---
 sphinx/themes/basic/static/websupport.js | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 863a57a5a..74e28c19a 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -23,9 +23,9 @@
     var columns = textarea.cols;
     var lineCount = 0;
     $.each(lines, function() {
-      lineCount += Math.ceil(this.length/columns) || 1;
+      lineCount += Math.ceil(this.length / columns) || 1;
     });
-    var height = lineHeight*(lineCount+1);
+    var height = lineHeight * (lineCount + 1);
     $(textarea).css('height', height);
   };
 })(jQuery);
@@ -158,8 +158,8 @@
     var popupWidth = $('div.popup_comment').width();
     $('div.popup_comment')
       .css({
-        'top': 100+$(window).scrollTop(),
-        'left': clientWidth/2-popupWidth/2,
+        'top': 100 + $(window).scrollTop(),
+        'left': clientWidth / 2 - popupWidth / 2,
         'position': 'absolute'
       })
       .fadeIn('fast', function() {
@@ -207,7 +207,7 @@
          appendComments(comments, ul);
          commentListEmpty = false;
        }
-       $('h3#comment_notification').slideUp(speed+200);
+       $('h3#comment_notification').slideUp(speed + 200);
        ul.slideDown(speed);
      },
      error: function(request, textStatus, error) {
@@ -448,11 +448,9 @@
 
     // If this is not an unvote, and the other vote arrow has
     // already been pressed, unpress it.
-    if ((d.value != 0) && (data.vote == d.value*-1)) {
-      $('#' + (d.value == 1 ? 'd' : 'u') + 'u' + d.comment_id)
-        .hide();
-      $('#' + (d.value == 1 ? 'd' : 'u') + 'v' + d.comment_id)
-        .show();
+    if ((d.value != 0) && (data.vote == d.value * -1)) {
+      $('#' + (d.value == 1 ? 'd' : 'u') + 'u' + d.comment_id).hide();
+      $('#' + (d.value == 1 ? 'd' : 'u') + 'v' + d.comment_id).show();
     }
 
     // Update the comments rating in the local data.

From bb0f113740d2c12daa3c47c7c37454945f914b99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Fri, 13 Aug 2010 17:07:15 +0200
Subject: [PATCH 119/127] Use document.createElement which is faster than
 parsing the html to create an element

---
 sphinx/themes/basic/static/websupport.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 74e28c19a..8405374d0 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -265,7 +265,7 @@
   function appendComments(comments, ul) {
     $.each(comments, function() {
       var div = createCommentDiv(this);
-      ul.append($('<li></li>').html(div));
+      ul.append($(document.createElement('li')).html(div));
       appendComments(this.children, div.find('ul.children'));
       // To avoid stagnating data, don't store the comments children in data.
       this.children = null;
@@ -292,7 +292,7 @@
       var siblings = getChildren(ul);
     }
 
-    var li = $('<li></li>');
+    var li = $(document.createElement('li'));
     li.hide();
 
     // Determine where in the parents children list to insert this comment.
@@ -596,7 +596,7 @@
    by context['id']. Items are always escaped.
   */
   function renderTemplate(template, context) {
-    var esc = $('<span></span>');
+    var esc = $(document.createElement('div'));
 
     function handle(ph, escape) {
       var cur = context;

From 030833e8c5dced1840eac5094d67fe313d92ef7f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Fri, 13 Aug 2010 17:10:22 +0200
Subject: [PATCH 120/127] Implement showError more efficiently

---
 sphinx/themes/basic/static/websupport.js | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 8405374d0..079497a06 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -612,10 +612,8 @@
   };
 
   function showError(message) {
-    $('<div class="popup_error">' +
-      '<h1>' + message + '</h1>' +
-      '</div>'
-    )
+    $(document.createElement('div').attr({class: 'popup_error'}))
+      .append($(document.createElement('h1').val(message)))
       .appendTo('body')
       .fadeIn("slow")
       .delay(2000)

From 2742399e800c2e677b15099b2adc65366899f9b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Fri, 13 Aug 2010 17:17:40 +0200
Subject: [PATCH 121/127] Implement $.fn.comment more efficiently

---
 sphinx/themes/basic/static/websupport.js | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 079497a06..cf0edf9b5 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -630,9 +630,12 @@
       var title = count + ' comment' + (count == 1 ? '' : 's');
       var image = count > 0 ? opts.commentBrightImage : opts.commentImage;
       $(this).append(
-        $('<a href="#" class="sphinx_comment"></a>')
-          .html('<img src="' + image + '" alt="comment" />')
-          .attr('title', title)
+        $(document.createElement('a')).attr({href: '#', class: 'spinx_comment'})
+          .append($(document.createElement('img')).attr({
+            src: image,
+            alt: 'comment',
+            title: title
+          }))
           .click(function(event) {
             event.preventDefault();
             show($(this).parent().attr('id'));

From 5be29e0894ec4e2ca3cf1894ae9aaa94a612745b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Fri, 13 Aug 2010 17:28:37 +0200
Subject: [PATCH 122/127] Fixed showError

---
 sphinx/themes/basic/static/websupport.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index cf0edf9b5..276d550b4 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -612,8 +612,8 @@
   };
 
   function showError(message) {
-    $(document.createElement('div').attr({class: 'popup_error'}))
-      .append($(document.createElement('h1').val(message)))
+    $(document.createElement('div')).attr({class: 'popup_error'})
+      .append($(document.createElement('h1')).text(message))
       .appendTo('body')
       .fadeIn("slow")
       .delay(2000)

From 3717927c83794ebfdd08832b8c53946754a1193c Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 13 Aug 2010 12:15:12 -0500
Subject: [PATCH 123/127] fixed bug in CombinedHtmlDiffer that clipped the last
 line.

---
 sphinx/themes/basic/static/websupport-templates.html | 2 +-
 sphinx/websupport/storage/differ.py                  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport-templates.html b/sphinx/themes/basic/static/websupport-templates.html
index 1ea58ab24..b28ec9644 100644
--- a/sphinx/themes/basic/static/websupport-templates.html
+++ b/sphinx/themes/basic/static/websupport-templates.html
@@ -57,7 +57,7 @@
 	  </span>
 	</p>
 	<pre class="proposal" id="pr<%id%>">
-	  <#proposal_diff#>
+<#proposal_diff#>
 	</pre>
 	<ul class="children" id="cl<%id%>"></ul>
       </div>
diff --git a/sphinx/websupport/storage/differ.py b/sphinx/websupport/storage/differ.py
index f0b6a8ea5..8d6c4a497 100644
--- a/sphinx/websupport/storage/differ.py
+++ b/sphinx/websupport/storage/differ.py
@@ -40,9 +40,9 @@ class CombinedHtmlDiff(object):
             try:
                 next = diff.pop(0)
             except IndexError:
-                self._handle_line(line)
+                html.append(self._handle_line(line))
                 break
-        return ''.join(html)
+        return ''.join(html).rstrip()
 
     def _handle_line(self, line, next=None):
         """Handle an individual line in a diff."""

From 642cfd08aadb36914573a0cf53a480c493e1cd57 Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 13 Aug 2010 14:32:30 -0500
Subject: [PATCH 124/127] readd modal focuser

---
 sphinx/themes/basic/static/websupport-templates.html | 1 +
 sphinx/themes/basic/static/websupport.js             | 8 ++++++--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/sphinx/themes/basic/static/websupport-templates.html b/sphinx/themes/basic/static/websupport-templates.html
index b28ec9644..22bbaa413 100644
--- a/sphinx/themes/basic/static/websupport-templates.html
+++ b/sphinx/themes/basic/static/websupport-templates.html
@@ -94,4 +94,5 @@
       <ul id="comment_ul"></ul>
     </div>
   </div>
+  <div id="focuser"></div>
 </div>
diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 276d550b4..0d8fab41c 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -110,9 +110,11 @@
       popup = $(renderTemplate(popupTemplate, opts));
       popup.find('textarea').autogrow();
 
-      commentTemplate = loadTemplate('#comment_template');
-      replyTemplate = loadTemplate('#reply_template');
+      commentTemplate = loadTemplate('comment_template');
+      replyTemplate = loadTemplate('reply_template');
+      var focuser = templates.find('#focuser');
       $('body').append(popup);
+      $('body').append(focuser);
       initEvents();
     });
   };
@@ -156,6 +158,7 @@
     // Position the popup and show it.
     var clientWidth = document.documentElement.clientWidth;
     var popupWidth = $('div.popup_comment').width();
+    $('div#focuser').fadeIn('fast');
     $('div.popup_comment')
       .css({
         'top': 100 + $(window).scrollTop(),
@@ -171,6 +174,7 @@
    Hide the comments popup window.
   */
   function hide() {
+    $('div#focuser').fadeOut('fast');
     $('div.popup_comment').fadeOut('fast', function() {
       $('ul#comment_ul').empty();
       $('h3#comment_notification').show();

From d62d568a003e8079fc2d47a5d2e609b2c6b88f4f Mon Sep 17 00:00:00 2001
From: Jacob Mason <jacoblmason@gmail.com>
Date: Fri, 13 Aug 2010 16:27:02 -0500
Subject: [PATCH 125/127] moved templates back into js, getting the html
 template file trys to load the images from template tags resulting in a bunch
 of 404's. This is a project for after pencils down date since it functions
 fine as is

---
 .../basic/static/websupport-templates.html    |  98 -------------
 sphinx/themes/basic/static/websupport.js      | 132 ++++++++++++++----
 sphinx/websupport/__init__.py                 |   3 +-
 3 files changed, 108 insertions(+), 125 deletions(-)
 delete mode 100644 sphinx/themes/basic/static/websupport-templates.html

diff --git a/sphinx/themes/basic/static/websupport-templates.html b/sphinx/themes/basic/static/websupport-templates.html
deleted file mode 100644
index 22bbaa413..000000000
--- a/sphinx/themes/basic/static/websupport-templates.html
+++ /dev/null
@@ -1,98 +0,0 @@
-<div id="templates">
-  <div id="reply_template">
-    <Li>
-      <div class="reply_div" id="rd<%id%>">
-	<form id="rf<%id%>">
-	  <textarea name="comment" cols="80"></textarea>
-          <input type="submit" value="add reply" />
-          <input type="hidden" name="parent" value="<%id%>" />
-          <input type="hidden" name="node" value="" />
-	</form>
-      </div>
-    </li>
-  </div>
-
-  <div id="comment_template">
-    <div  id="cd<%id%>" class="spxcdiv">
-      <div class="vote">
-	<div class="arrow">
-	  <a href="#" id="uv<%id%>" class="vote">
-	    <img src="<%upArrow%>" />
-	  </a>
-	  <a href="#" id="uu<%id%>" class="un vote">
-	    <img src="<%upArrowPressed%>" />
-	  </a>
-	</div>
-	<div class="arrow">
-	  <a href="#" id="dv<%id%>" class="vote">
-	    <img src="<%downArrow%>" id="da<%id%>" />
-	  </a>
-	  <a href="#" id="du<%id%>" class="un vote">
-	    <img src="<%downArrowPressed%>" />
-	  </a>
-	</div>
-      </div>
-      <div class="comment_content">
-	<p class="tagline comment">
-	  <span class="user_id"><%username%></span>
-	  <span class="rating"><%pretty_rating%></span>
-	  <span class="delta"><%time.delta%></span>
-	</p>
-	<p class="comment_text comment"><%text%></p>
-	<p class="comment_opts comment">
-	  <a href="#" class="reply hidden" id="rl<%id%>">reply &#9657;</a>
-	  <a href="#" class="close_reply" id="cr<%id%>">reply &#9663;</a>
-	  <a href="#" id="sp<%id%>" class="show_proposal">
-	    proposal &#9657;
-	  </a>
-	  <a href="#" id="hp<%id%>" class="hide_proposal">
-	    proposal &#9663;
-	  </a>
-	  <a href="#" id="dc<%id%>" class="delete_comment hidden">
-	    delete
-	  </a>
-	  <span id="cm<%id%>" class="moderation hidden">
-	    <a href="#" id="ac<%id%>" class="accept_comment">accept</a>
-	    <a href="#" id="rc<%id%>" class="reject_comment">reject</a>
-	  </span>
-	</p>
-	<pre class="proposal" id="pr<%id%>">
-<#proposal_diff#>
-	</pre>
-	<ul class="children" id="cl<%id%>"></ul>
-      </div>
-      <div class="clearleft"></div>
-    </div>
-  </div>
-
-  <div id="popup_template">
-    <div class="popup_comment">
-      <a id="comment_close" href="#">x</a>
-      <h1>Comments</h1>
-      <form method="post" id="comment_form" action="/docs/add_comment">
-	<textarea name="comment" cols="80"></textarea>
-	<p class="propose_button">
-	  <a href="#" class="show_propose_change">
-	    Propose a change &#9657;
-	  </a>
-	  <a href="#" class="hide_propose_change">
-	    Propose a change &#9663;
-	  </a>
-	</p>
-	<textarea name="proposal" cols="80" spellcheck="false"></textarea>
-	<input type="submit" value="add comment" id="comment_button" />
-	<input type="hidden" name="node" />
-	<input type="hidden" name="parent" value="" />
-	<p class="sort_options">
-	  Sort by:
-	  <a href="#" class="sort_option" id="rating">top</a>
-	  <a href="#" class="sort_option" id="ascage">newest</a>
-	  <a href="#" class="sort_option" id="age">oldest</a>
-	</p>
-      </form>
-      <h3 id="comment_notification">loading comments... <img src="<%loadingImage%>" alt="" /></h3>
-      <ul id="comment_ul"></ul>
-    </div>
-  </div>
-  <div id="focuser"></div>
-</div>
diff --git a/sphinx/themes/basic/static/websupport.js b/sphinx/themes/basic/static/websupport.js
index 0d8fab41c..a0aa79170 100644
--- a/sphinx/themes/basic/static/websupport.js
+++ b/sphinx/themes/basic/static/websupport.js
@@ -31,10 +31,11 @@
 })(jQuery);
 
 (function($) {
-  var commentListEmpty, popup, comp, commentTemplate, replyTemplate;
+  var commentListEmpty, popup, comp;
 
   function init() {
     initTemplates();
+    initEvents();
     initComparator();
   };
 
@@ -94,29 +95,12 @@
   };
 
   function initTemplates() {
-    var templateURL = opts.staticDir + '/_static/websupport-templates.html';
-    $.get(templateURL, function(data) {
-      var templates = $(data);
-      function loadTemplate(id) {
-        var html = templates.find('#' + id).html();
-        html = html.replace(/(&lt;)|(%3C)/g, "<");
-        html = html.replace(/(&gt;)|(%3E)/g, ">");
-        return html;
-      };
-      // Create our popup div, the same div is recycled each time comments
-      // are displayed.
-      // Setup autogrow on the textareas
-      var popupTemplate = loadTemplate('popup_template');
-      popup = $(renderTemplate(popupTemplate, opts));
-      popup.find('textarea').autogrow();
-
-      commentTemplate = loadTemplate('comment_template');
-      replyTemplate = loadTemplate('reply_template');
-      var focuser = templates.find('#focuser');
-      $('body').append(popup);
-      $('body').append(focuser);
-      initEvents();
-    });
+    // Create our popup div, the same div is recycled each time comments
+    // are displayed.
+    popup = $(renderTemplate(popupTemplate, opts));
+    // Setup autogrow on the textareas
+    popup.find('textarea').autogrow();
+    $('body').append(popup);
   };
 
   /*
@@ -662,11 +646,109 @@
     downArrow: '/static/_static/down.png',
     upArrowPressed: '/static/_static/up-pressed.png',
     downArrowPressed: '/static/_static/down-pressed.png',
-    staticDir: '/static',
     voting: false,
     moderator: false
   }, COMMENT_OPTIONS);
 
+  var replyTemplate = '\
+    <li>\
+      <div class="reply_div" id="rd<%id%>">\
+        <form id="rf<%id%>">\
+          <textarea name="comment" cols="80"></textarea>\
+          <input type="submit" value="add reply" />\
+          <input type="hidden" name="parent" value="<%id%>" />\
+          <input type="hidden" name="node" value="" />\
+        </form>\
+      </div>\
+    </li>';
+
+  var commentTemplate = '\
+    <div  id="cd<%id%>" class="spxcdiv">\
+      <div class="vote">\
+        <div class="arrow">\
+          <a href="#" id="uv<%id%>" class="vote">\
+            <img src="<%upArrow%>" />\
+          </a>\
+          <a href="#" id="uu<%id%>" class="un vote">\
+            <img src="<%upArrowPressed%>" />\
+          </a>\
+        </div>\
+        <div class="arrow">\
+          <a href="#" id="dv<%id%>" class="vote">\
+            <img src="<%downArrow%>" id="da<%id%>" />\
+          </a>\
+          <a href="#" id="du<%id%>" class="un vote">\
+            <img src="<%downArrowPressed%>" />\
+          </a>\
+        </div>\
+      </div>\
+      <div class="comment_content">\
+        <p class="tagline comment">\
+          <span class="user_id"><%username%></span>\
+          <span class="rating"><%pretty_rating%></span>\
+          <span class="delta"><%time.delta%></span>\
+        </p>\
+        <p class="comment_text comment"><%text%></p>\
+        <p class="comment_opts comment">\
+          <a href="#" class="reply hidden" id="rl<%id%>">reply &#9657;</a>\
+          <a href="#" class="close_reply" id="cr<%id%>">reply &#9663;</a>\
+          <a href="#" id="sp<%id%>" class="show_proposal">\
+            proposal &#9657;\
+          </a>\
+          <a href="#" id="hp<%id%>" class="hide_proposal">\
+            proposal &#9663;\
+          </a>\
+          <a href="#" id="dc<%id%>" class="delete_comment hidden">\
+            delete\
+          </a>\
+          <span id="cm<%id%>" class="moderation hidden">\
+            <a href="#" id="ac<%id%>" class="accept_comment">accept</a>\
+            <a href="#" id="rc<%id%>" class="reject_comment">reject</a>\
+          </span>\
+        </p>\
+        <pre class="proposal" id="pr<%id%>">\
+<#proposal_diff#>\
+        </pre>\
+          <ul class="children" id="cl<%id%>"></ul>\
+        </div>\
+        <div class="clearleft"></div>\
+      </div>\
+    </div>';
+
+  var popupTemplate = '\
+    <div id="popup_template">\
+      <div class="popup_comment">\
+        <a id="comment_close" href="#">x</a>\
+        <h1>Comments</h1>\
+        <form method="post" id="comment_form" action="/docs/add_comment">\
+          <textarea name="comment" cols="80"></textarea>\
+          <p class="propose_button">\
+            <a href="#" class="show_propose_change">\
+              Propose a change &#9657;\
+            </a>\
+            <a href="#" class="hide_propose_change">\
+              Propose a change &#9663;\
+            </a>\
+          </p>\
+          <textarea name="proposal" cols="80" spellcheck="false"></textarea>\
+          <input type="submit" value="add comment" id="comment_button" />\
+          <input type="hidden" name="node" />\
+          <input type="hidden" name="parent" value="" />\
+          <p class="sort_options">\
+            Sort by:\
+            <a href="#" class="sort_option" id="rating">top</a>\
+            <a href="#" class="sort_option" id="ascage">newest</a>\
+            <a href="#" class="sort_option" id="age">oldest</a>\
+          </p>\
+        </form>\
+        <h3 id="comment_notification">loading comments... <img src="' +
+          opts.loadingImage + '" alt="" /></h3>\
+        <ul id="comment_ul"></ul>\
+      </div>\
+    </div>\
+    <div id="focuser"></div>';
+
+
   $(document).ready(function() {
     init();
   });
diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py
index 939428a6c..cc065b7f7 100644
--- a/sphinx/websupport/__init__.py
+++ b/sphinx/websupport/__init__.py
@@ -376,8 +376,7 @@ class WebSupport(object):
                 ('upArrow', 'up.png'),
                 ('upArrowPressed', 'up-pressed.png'),
                 ('downArrow', 'down.png'),
-                ('downArrowPressed', 'down-pressed.png'),
-                ('staticDir', '/' + self.staticdir)
+                ('downArrowPressed', 'down-pressed.png')
             ]
             for key, value in static_urls:
                 self.base_comment_opts[key] = \

From 1f0b25be796c8d62a3607d4e6498b43ed1cf8481 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Sat, 14 Aug 2010 11:17:38 +0200
Subject: [PATCH 126/127] Fix finish handler of the websupport builder

---
 sphinx/builders/websupport.py | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 16e3a82bd..0c92c646d 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -151,12 +151,15 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
 
     def handle_finish(self):
         StandaloneHTMLBuilder.handle_finish(self)
-        shutil.move(path.join(self.outdir, '_images'),
-                    path.join(self.app.builddir, self.app.staticdir,
-                              '_images'))
-        shutil.move(path.join(self.outdir, '_static'),
-                    path.join(self.app.builddir, self.app.staticdir,
-                              '_static'))
+        directories = ['_images', '_static']
+        for directory in directories:
+            try:
+                shutil.move(path.join(self.outdir, directory),
+                            path.join(self.app.builddir, self.app.staticdir,
+                                      directory))
+            except IOError:
+                # in case any of these directories don't exist
+                pass
         for f in glob(path.join(self.doctreedir, '*.doctree.old')):
             os.remove(f)
 

From 7e7134e029dbf1ba88cdc3cb4aade11a84fdd783 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Neuh=C3=A4user?= <ich@danielneuhaeuser.de>
Date: Sat, 14 Aug 2010 11:22:40 +0200
Subject: [PATCH 127/127] Use the highest protocol to pickle doctrees and use
 the constants provided by the pickle module

---
 sphinx/builders/websupport.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py
index 0c92c646d..e43c46dee 100644
--- a/sphinx/builders/websupport.py
+++ b/sphinx/builders/websupport.py
@@ -137,7 +137,7 @@ class WebSupportBuilder(StandaloneHTMLBuilder):
         ensuredir(path.dirname(outfilename))
         f = open(outfilename, 'wb')
         try:
-            pickle.dump(doc_ctx, f, 2)
+            pickle.dump(doc_ctx, f, pickle.HIGHEST_PROTOCOL)
         finally:
             f.close()