Merge pull request ipython#168 from Carreau/some-changes

Some changes

 - Import some stuff at higher level to have cleaner API.
 - Allow resource dict to be passed with from_notebook_node
 - Doc fixes.
 - change (backward compatible) api for Transformer, create dummy call() method without dunder. Allows simple logics when inheriting ActivatableTransformer.

nbconvert/exporters/__init__.py

@@ -0,0 +1,11 @@
+from basichtml import BasicHtmlExporter
+#from export import
+#from exporter import
+from fullhtml import FullHtmlExporter
+from latex import LatexExporter
+from markdown import MarkdownExporter
+from python import PythonExporter
+#from reveal import
+from rst import RstExporter
+from sphinx_howto import SphinxHowtoExporter
+from sphinx_manual import SphinxManualExporter

nbconvert/exporters/exporter.py

@@ -49,6 +49,25 @@
 #Jinja2 extensions to load.
 JINJA_EXTENSIONS = ['jinja2.ext.loopcontrols']
 
+default_filters = {
+        'indent': indent,
+        'markdown': markdown,
+        'ansi2html': nbconvert.filters.ansi.ansi2html,
+        'filter_data_type': nbconvert.filters.datatypefilter.DataTypeFilter,
+        'get_lines': nbconvert.filters.strings.get_lines,
+        'highlight': nbconvert.filters.highlight.highlight,
+        'highlight2html': nbconvert.filters.highlight.highlight,
+        'highlight2latex': nbconvert.filters.highlight.highlight2latex,
+        'markdown2latex': nbconvert.filters.markdown.markdown2latex,
+        'markdown2rst': nbconvert.filters.markdown.markdown2rst,
+        'pycomment': nbconvert.filters.strings.python_comment,
+        'rm_ansi': nbconvert.filters.ansi.remove_ansi,
+        'rm_dollars': nbconvert.filters.strings.strip_dollars,
+        'rm_fake': nbconvert.filters.strings.rm_fake,
+        'rm_math_space': nbconvert.filters.latex.rm_math_space,
+        'wrap': nbconvert.filters.strings.wrap
+}
+
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
@@ -61,8 +80,15 @@ class Exporter(Configurable):
     transformers provided by default suffice, there is no need to inherit from
     this class.  Instead, override the template_file and file_extension
     traits via a config file.
-    """
     
+    {filters}
+    """
+
+
+
+    __doc__ = __doc__.format(filters = '- '+'\n    - '.join(default_filters.keys()))
+
+
     template_file = Unicode(
             '', config=True,
             help="Name of the template file to use")
@@ -107,10 +133,11 @@ def __init__(self, transformers=None, filters=None, config=None, **kw):
             the Jinja template engine.  Any transformers specified here 
             will override existing transformers if a naming conflict
             occurs.
-        filters : list[of filter]
-            Custom filters to make accessible to the Jinja templates.  Any
-            filters specified here will override existing filters if a
-            naming conflict occurs.
+        filters : dict[of filter]
+            filters specified here will override existing filters if a naming
+            conflict occurs. Filters are availlable in jinja template through
+            the name of the corresponding key. Cf class docstring for
+            availlable default filters.
         config : config
             User configuration instance.
         """
@@ -141,16 +168,20 @@ def __init__(self, transformers=None, filters=None, config=None, **kw):
                     self.environment.filters[key] = user_filter
 
 
-    def from_notebook_node(self, nb):
+    def from_notebook_node(self, nb, resources=None):
         """
         Convert a notebook from a notebook node instance.
     
         Parameters
         ----------
         nb : Notebook node
+        resources : a dict of additional resources that
+                can be accessed read/write by transformers
+                and filters.
         """
-
-        nb, resources = self._preprocess(nb)
+        if resources is None:
+            resources = {}
+        nb, resources = self._preprocess(nb, resources)
 
         #Load the template file.
         self.template = self.environment.get_template(self.template_file+self.template_extension)
@@ -249,23 +280,8 @@ def _register_filters(self):
         """
         Register all of the filters required for the exporter.
         """
-
-        self.register_filter('indent', indent)
-        self.register_filter('markdown', markdown)
-        self.register_filter('ansi2html', nbconvert.filters.ansi.ansi2html)
-        self.register_filter('filter_data_type', nbconvert.filters.datatypefilter.DataTypeFilter)
-        self.register_filter('get_lines', nbconvert.filters.strings.get_lines)
-        self.register_filter('highlight', nbconvert.filters.highlight.highlight)
-        self.register_filter('highlight2html', nbconvert.filters.highlight.highlight) 
-        self.register_filter('highlight2latex', nbconvert.filters.highlight.highlight2latex)
-        self.register_filter('markdown2latex', nbconvert.filters.markdown.markdown2latex)
-        self.register_filter('markdown2rst', nbconvert.filters.markdown.markdown2rst)
-        self.register_filter('pycomment', nbconvert.filters.strings.python_comment)
-        self.register_filter('rm_ansi', nbconvert.filters.ansi.remove_ansi)
-        self.register_filter('rm_dollars', nbconvert.filters.strings.strip_dollars)
-        self.register_filter('rm_fake', nbconvert.filters.strings.rm_fake)
-        self.register_filter('rm_math_space', nbconvert.filters.latex.rm_math_space)
-        self.register_filter('wrap', nbconvert.filters.strings.wrap)
+        for k,v in default_filters.iteritems():
+            self.register_filter(k,v)
 
 
     def _init_environment(self):
@@ -296,7 +312,7 @@ def _init_environment(self):
             self.environment.comment_end_string = self.jinja_comment_block_end
 
 
-    def _preprocess(self, nb):
+    def _preprocess(self, nb, resources):
         """
         Preprocess the notebook before passing it into the Jinja engine.
         To preprocess the notebook is to apply all of the 
@@ -305,13 +321,15 @@ def _preprocess(self, nb):
         ----------
         nb : notebook node
             notebook that is being exported.
+        resources : a dict of additional resources that
+            can be accessed read/write by transformers
+            and filters.
         """
 
-        #Dict of 'resources' that can be filled by the transformers.
-        resources = {}
 
         #Run each transformer on the notebook.  Carry the output along
         #to each transformer
         for transformer in self.transformers:
             nb, resources = transformer(nb, resources)
         return nb, resources
+

nbconvert/transformers/__init__.py

@@ -0,0 +1,10 @@
+
+# Class base Transformers
+from activatable import ActivatableTransformer
+from base import ConfigurableTransformer
+from extractfigure import ExtractFigureTransformer
+from latex import LatexTransformer
+from sphinx import SphinxTransformer
+
+# decorated function Transformers
+from coalescestreams import coalesce_streams

nbconvert/transformers/base.py

@@ -53,6 +53,9 @@ def __init__(self, config=None, **kw):
 
 
     def __call__(self, nb, resources):
+        return self.call(nb,resources)
+
+    def call(self, nb, resources):
         """
         Transformation to apply on each notebook.
         
@@ -95,4 +98,4 @@ def cell_transform(self, cell, resources, index):
 
         raise NotImplementedError('should be implemented by subclass')
         return cell, resources
-    
+

nbconvert/transformers/sphinx.py

@@ -111,28 +111,7 @@ class SphinxTransformer(ActivatableTransformer):
     overridetitle = Unicode("", config=True, help="")
 
 
-    def __call__(self, nb, resources):
-        """
-        Entrypoint
-        Since we are not interested in any additional manipulation on a cell
-        by cell basis, we do not  call the base implementation.
-        
-        Parameters
-        ----------
-        nb : NotebookNode
-            Notebook being converted
-        resources : dictionary
-            Additional resources used in the conversion process.  Allows
-            transformers to pass variables into the Jinja engine.
-        """
-
-        if self.enabled:
-            return self.transform(nb, resources)
-        else:
-            return nb,resources
-
-
-    def transform(self, nb, resources):
+    def call(self, nb, resources):
         """
         Sphinx transformation to apply on each notebook.
         
@@ -279,4 +258,4 @@ def _prompt_chapter_title_style(self):
                     6: "(for international documents)"}
 
         return nbconvert.utils.console.prompt_dictionary(styles, menu_comments=comments)
-    
+