"Initial commit": Added sphinx.websupport module, as well as a builder and writer for the web support package.

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.

sphinx/builders/__init__.py

@@ -329,4 +329,5 @@ BUILTIN_BUILDERS = {
     'man':        ('manpage', 'ManualPageBuilder'),
     'changes':    ('changes', 'ChangesBuilder'),
     'linkcheck':  ('linkcheck', 'CheckExternalLinksBuilder'),
+    'websupport': ('websupport', 'WebSupportBuilder'),
 }

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

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()

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

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=''

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