Add GNOME Devhelp builder

doc/builders.rst

@@ -36,6 +36,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 0.6
 
+.. module:: sphinx.builders.htmlhelp
 .. class:: HTMLHelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
@@ -44,6 +45,24 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``htmlhelp``.
 
+.. module:: sphinx.builders.qthelp
+.. class:: QtHelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates Qt help collection support files that allow
+   the Qt collection generator to compile them.
+
+   Its name is ``qthelp``.
+
+.. module:: sphinx.builders.devhelp
+.. class:: DevhelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates `GNOME Devhelp <http://live.gnome.org/devhelp>`__ 
+   support file that allows the GNOME Devhelp reader to view them.
+
+   Its name is ``devhelp``.
+
 .. module:: sphinx.builders.latex
 .. class:: LaTeXBuilder
 

doc/sphinx-build.1

@@ -31,6 +31,9 @@ Generates files for CHM generation.
 \fBqthelp\fR
 Generates files for Qt help collection generation.
 .TP
+\fBdevhelp\fR
+Generates files for GNOME Devhelp help viewer.
+.TP
 \fBlatex\fR
 Generates a LaTeX version of the documentation.
 .TP

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'),

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

sphinx/config.py

@@ -94,6 +94,9 @@ class Config(object):
         # Qt help only options
         qthelp_basename = (lambda self: make_filename(self.project), None),
 
+        # Devhelp only options
+        devhelp_basename = (lambda self: make_filename(self.project), None),
+
         # LaTeX options
         latex_documents = ([], None),
         latex_logo = (None, None),

sphinx/quickstart.py

@@ -280,6 +280,7 @@ help:
 \t@echo "  json      to make JSON files"
 \t@echo "  htmlhelp  to make HTML files and a HTML help project"
 \t@echo "  qthelp    to make HTML files and a qthelp project"
+\t@echo "  devhelp   to make HTML files and a Devhelp project"
 \t@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 \t@echo "  latexpdf  to make LaTeX files and run them through pdflatex"
 \t@echo "  changes   to make an overview of all changed/added/deprecated items"
@@ -325,6 +326,15 @@ qthelp:
 \t@echo "To view the help file:"
 \t@echo "# assistant -collectionFile %(rbuilddir)s/qthelp/%(project_fn)s.qhc"
 
+devhelp:
+\t$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) %(rbuilddir)s/devhelp
+\t@echo
+\t@echo "Build finished."
+\t@echo "To view the help file:"
+\t@echo "# mkdir -p $$HOME/.local/share/devhelp/%(project_fn)s"
+\t@echo "# ln -s %(rbuilddir)s/devhelp $$HOME/.local/share/devhelp/%(project_fn)s"
+\t@echo "# devhelp"
+
 latex:
 \t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) %(rbuilddir)s/latex
 \t@echo
@@ -377,6 +387,7 @@ if "%%1" == "help" (
 \techo.  json      to make JSON files
 \techo.  htmlhelp  to make HTML files and a HTML help project
 \techo.  qthelp    to make HTML files and a qthelp project
+\techo.  devhelp   to make HTML files and a Devhelp project
 \techo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
 \techo.  changes   to make an overview over all changed/added/deprecated items
 \techo.  linkcheck to check all external links for integrity
@@ -437,6 +448,13 @@ if "%%1" == "qthelp" (
 \tgoto end
 )
 
+if "%%1" == "devhelp" (
+\t%%SPHINXBUILD%% -b devhelp %%ALLSPHINXOPTS%% %(rbuilddir)s/devhelp
+\techo.
+\techo.Build finished.
+\tgoto end
+)
+
 if "%%1" == "latex" (
 \t%%SPHINXBUILD%% -b latex %%ALLSPHINXOPTS%% %(rbuilddir)s/latex
 \techo.