From 099a58e0b7b37b0737c83253fda5b1ff344bdec2 Mon Sep 17 00:00:00 2001 From: jacob Date: Sun, 30 May 2010 21:33:04 -0500 Subject: [PATCH] "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