Add support for using documentation siphons in multiple ways

Experiental support for generating  multiple output formats from the
same siphoned data.

Adds a contrived example to generate a plain list of all CLI commands
(the "itemlist" format).

Eventually we can consider moving the tempate procesisng into the
Output class as well as a way to override how the data is traversed
(ordered).

Change-Id: I77629a74a8fa0c7e583993469dc50491f72f13e7
Signed-off-by: Chris Luke <chrisy@flirble.org>

1 files changed, 59 insertions, 20 deletions

diff --git a/doxygen/siphon/process.py b/doxygen/siphon/process.py
index 34e829c5298..f3119ea89e8 100644
--- a/doxygen/siphon/process.py
+++ b/doxygen/siphon/process.py
@@ -20,6 +20,9 @@ import logging, os,sys, cgi, json, jinja2, HTMLParser
 """Mapping of known processors to their classes"""
 siphons = {}
 
+"""Mapping of known output formats to their classes"""
+formats = {}
+
 
 """Generate rendered output for siphoned data."""
 class Siphon(object):
@@ -51,28 +54,36 @@ class Siphon(object):
     """Template environment, if we're using templates"""
     _tplenv = None
 
-    def __init__(self, template_directory=None):
+    def __init__(self, template_directory, format):
         super(Siphon, self).__init__()
         self.log = logging.getLogger("siphon.process.%s" % self.name)
 
-        if template_directory is not None:
-          self.template_directory = template_directory
-          searchpath = [
-              template_directory + "/" + self.name,
-              template_directory + "/" + "default",
-          ]
-          loader = jinja2.FileSystemLoader(searchpath=searchpath)
-          self._tplenv = jinja2.Environment(
-              loader=loader,
-              trim_blocks=True,
-              keep_trailing_newline=True)
-
-          # Convenience, get a reference to the internal escape and
-          # unescape methods in cgi and HTMLParser. These then become
-          # available to templates to use, if needed.
-          self._h = HTMLParser.HTMLParser()
-          self.escape = cgi.escape
-          self.unescape = self._h.unescape
+        # Get our output format details
+        fmt_klass = formats[format]
+        fmt = fmt_klass()
+        self._format = fmt
+
+        # Sort out the template search path
+        def _tpldir(name):
+            return os.sep.join((template_directory, fmt.name, name))
+
+        self.template_directory = template_directory
+        searchpath = [
+            _tpldir(self.name),
+            _tpldir("default"),
+        ]
+        loader = jinja2.FileSystemLoader(searchpath=searchpath)
+        self._tplenv = jinja2.Environment(
+            loader=loader,
+            trim_blocks=True,
+            keep_trailing_newline=True)
+
+        # Convenience, get a reference to the internal escape and
+        # unescape methods in cgi and HTMLParser. These then become
+        # available to templates to use, if needed.
+        self._h = HTMLParser.HTMLParser()
+        self.escape = cgi.escape
+        self.unescape = self._h.unescape
 
 
     # Output renderers
@@ -157,7 +168,7 @@ class Siphon(object):
 
     """Template processor"""
     def template(self, name, **kwargs):
-      tpl = self._tplenv.get_template(name + ".md")
+      tpl = self._tplenv.get_template(name + self._format.extension)
       return tpl.render(
             this=self,
             **kwargs)
@@ -270,3 +281,31 @@ class Siphon(object):
 
         # Deliver the accumulated body output
         out.write(contents)
+
+
+"""Output format class"""
+class Format(object):
+
+    """Name of this output format"""
+    name = None
+
+    """Expected file extension of templates that build this format"""
+    extension = None
+
+
+"""Markdown output format"""
+class FormatMarkdown(Format):
+    name = "markdown"
+    extension = ".md"
+
+# Register 'markdown'
+formats["markdown"] = FormatMarkdown
+
+
+"""Itemlist output format"""
+class FormatItemlist(Format):
+    name = "itemlist"
+    extension = ".itemlist"
+
+# Register 'itemlist'
+formats["itemlist"] = FormatItemlist