diff options
Diffstat (limited to 'sphinx/builders')
| -rw-r--r-- | sphinx/builders/__init__.py | 1 | ||||
| -rw-r--r-- | sphinx/builders/changes.py | 1 | ||||
| -rw-r--r-- | sphinx/builders/devhelp.py | 132 | ||||
| -rw-r--r-- | sphinx/builders/html.py | 40 |
4 files changed, 164 insertions, 10 deletions
diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 3fb0d469..a8fc8871 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -386,6 +386,7 @@ BUILTIN_BUILDERS = { 'json': ('html', 'JSONHTMLBuilder'), 'web': ('html', 'PickleHTMLBuilder'), 'htmlhelp': ('htmlhelp', 'HTMLHelpBuilder'), + 'devhelp': ('devhelp', 'DevhelpBuilder'), 'qthelp': ('qthelp', 'QtHelpBuilder'), 'latex': ('latex', 'LaTeXBuilder'), 'text': ('text', 'TextBuilder'), diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py index d9898aeb..c1ea14a8 100644 --- a/sphinx/builders/changes.py +++ b/sphinx/builders/changes.py @@ -93,6 +93,7 @@ class ChangesBuilder(Builder): 'libchanges': sorted(libchanges.iteritems()), 'apichanges': sorted(apichanges), 'otherchanges': sorted(otherchanges.iteritems()), + 'show_copyright': self.config.html_show_copyright, 'show_sphinx': self.config.html_show_sphinx, } f = codecs.open(path.join(self.outdir, 'index.html'), 'w', 'utf8') diff --git a/sphinx/builders/devhelp.py b/sphinx/builders/devhelp.py new file mode 100644 index 00000000..ba117e62 --- /dev/null +++ b/sphinx/builders/devhelp.py @@ -0,0 +1,132 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.devhelp + ~~~~~~~~~~~~~~~~~~~~~~~ + + Build HTML documentation and Devhelp_ support files. + + .. _Devhelp: http://live.gnome.org/devhelp + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import cgi +import sys +from os import path + +from docutils import nodes + +from sphinx import addnodes +from sphinx.builders.html import StandaloneHTMLBuilder + +try: + import xml.etree.ElementTree as etree +except ImportError: + try: + import lxml.etree as etree + except ImportError: + try: + import elementtree.ElementTree as etree + except ImportError: + import cElementTree.ElemenTree as etree + +try: + import gzip + def comp_open(filename, mode='rb'): + return gzip.open(filename + '.gz', mode) +except ImportError: + def comp_open(filename, mode='rb'): + return open(filename, mode) + + +class DevhelpBuilder(StandaloneHTMLBuilder): + """ + Builder that also outputs GNOME Devhelp file. + + """ + name = 'devhelp' + + # don't copy the reST source + copysource = False + supported_image_types = ['image/png', 'image/gif', 'image/jpeg'] + + # don't add links + add_permalinks = False + # don't add sidebar etc. + embedded = True + + def init(self): + StandaloneHTMLBuilder.init(self) + self.out_suffix = '.html' + + def handle_finish(self): + self.build_devhelp(self.outdir, self.config.devhelp_basename) + + def build_devhelp(self, outdir, outname): + self.info('dumping devhelp index...') + + # Basic info + root = etree.Element('book', + title=self.config.html_title, + name=self.config.project, + link="index.html", + version=self.config.version) + tree = etree.ElementTree(root) + + # TOC + chapters = etree.SubElement(root, 'chapters') + + tocdoc = self.env.get_and_resolve_doctree( + self.config.master_doc, self, prune_toctrees=False) + + def write_toc(node, parent): + if isinstance(node, addnodes.compact_paragraph) or \ + isinstance(node, nodes.bullet_list): + for subnode in node: + write_toc(subnode, parent) + elif isinstance(node, nodes.list_item): + item = etree.SubElement(parent, 'sub') + for subnode in node: + write_toc(subnode, item) + elif isinstance(node, nodes.reference): + parent.attrib['link'] = node['refuri'] + parent.attrib['name'] = node.astext().encode('utf-8') + + def istoctree(node): + return isinstance(node, addnodes.compact_paragraph) and \ + node.has_key('toctree') + + for node in tocdoc.traverse(istoctree): + write_toc(node, chapters) + + # Index + functions = etree.SubElement(root, 'functions') + index = self.env.create_index(self) + + def write_index(title, refs, subitems): + if len(refs) == 0: + pass + elif len(refs) == 1: + etree.SubElement(functions, 'function', + name=title, link=refs[0]) + else: + for i, ref in enumerate(refs): + etree.SubElement(functions, 'function', + name="%s [%d]" % (title, i), link=ref) + + if subitems: + for subitem in subitems: + write_index(subitem[0], subitem[1], []) + + for (key, group) in index: + for title, (refs, subitems) in group: + write_index(title, refs, subitems) + + # Dump the XML file + f = comp_open(path.join(outdir, outname + '.devhelp'), 'w') + try: + tree.write(f) + finally: + f.close() diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index c2b00fb5..54327fa1 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -22,7 +22,7 @@ except ImportError: from docutils import nodes from docutils.io import DocTreeInput, StringOutput -from docutils.core import publish_parts +from docutils.core import Publisher, publish_parts from docutils.utils import new_document from docutils.frontend import OptionParser from docutils.readers.doctree import Reader as DoctreeReader @@ -71,6 +71,11 @@ class StandaloneHTMLBuilder(Builder): # This is a class attribute because it is mutated by Sphinx.add_javascript. script_files = ['_static/jquery.js', '_static/doctools.js'] + # Dito for this one. + css_files = [] + + # cached publisher object for snippets + _publisher = None def init(self): # a hash of all config values that, if changed, cause a full rebuild @@ -110,7 +115,8 @@ class StandaloneHTMLBuilder(Builder): style = self.theme.get_confstr('theme', 'pygments_style', 'none') else: style = 'sphinx' - self.highlighter = PygmentsBridge('html', style) + self.highlighter = PygmentsBridge('html', style, + self.config.trim_doctest_flags) def init_translator_class(self): if self.config.html_translator_class: @@ -180,13 +186,24 @@ class StandaloneHTMLBuilder(Builder): """Utility: Render a lone doctree node.""" doc = new_document('<partial node>') doc.append(node) - return publish_parts( - doc, - source_class=DocTreeInput, - reader=DoctreeReader(), - writer=HTMLWriter(self), - settings_overrides={'output_encoding': 'unicode'} - ) + + if self._publisher is None: + self._publisher = Publisher( + source_class = DocTreeInput, + destination_class=StringOutput) + self._publisher.set_components('standalone', + 'restructuredtext', 'pseudoxml') + + pub = self._publisher + + pub.reader = DoctreeReader() + pub.writer = HTMLWriter(self) + pub.process_programmatic_settings( + None, {'output_encoding': 'unicode'}, None) + pub.set_source(doc, None) + pub.set_destination(None, None) + pub.publish() + return pub.writer.parts def prepare_writing(self, docnames): from sphinx.search import IndexBuilder @@ -244,11 +261,13 @@ class StandaloneHTMLBuilder(Builder): use_opensearch = self.config.html_use_opensearch, docstitle = self.config.html_title, shorttitle = self.config.html_short_title, + show_copyright = self.config.html_show_copyright, show_sphinx = self.config.html_show_sphinx, has_source = self.config.html_copy_source, show_source = self.config.html_show_sourcelink, file_suffix = self.out_suffix, script_files = self.script_files, + css_files = self.css_files, sphinx_version = __version__, style = stylename, rellinks = rellinks, @@ -646,6 +665,7 @@ class StandaloneHTMLBuilder(Builder): ctx['pathto'] = pathto ctx['hasdoc'] = lambda name: name in self.env.all_docs ctx['customsidebar'] = self.config.html_sidebars.get(pagename) + ctx['encoding'] = encoding = self.config.html_output_encoding ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw) ctx.update(addctx) @@ -658,7 +678,7 @@ class StandaloneHTMLBuilder(Builder): # outfilename's path is in general different from self.outdir ensuredir(path.dirname(outfilename)) try: - f = codecs.open(outfilename, 'w', 'utf-8') + f = codecs.open(outfilename, 'w', encoding) try: f.write(output) finally: |