Cleanup and refactor, transformers

nbconvert/transformers/activatable.py

@@ -1,19 +1,53 b''
+"""
+Contains base transformer with an enable/disable flag.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2013, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
 from .base import ConfigurableTransformer
 from IPython.utils.traitlets import (Bool)
 
-class ActivatableTransformer(ConfigurableTransformer):
-    """A simple ConfigurableTransformers that have an enabled flag
+#-----------------------------------------------------------------------------
+# Classes and Functions
+#-----------------------------------------------------------------------------
 
-    Inherit from that if you just want to have a transformer which is
-    no-op by default but can be activated in profiles with
+class ActivatableTransformer(ConfigurableTransformer):
+    """ConfigurableTransformer that has an enabled flag
 
-    c.YourTransformerName.enabled = True
+    Inherit from this if you just want to have a transformer which is
+    enabled by default and can be disabled via the config by
+        'c.YourTransformerName.enabled = True'
     """
 
     enabled = Bool(True, config=True)
 
-    def __call__(self, nb, other):
+    def __call__(self, nb, resources):
+        """
+        Transformation to apply on each notebook.
+        
+        You should return modified nb, resources.
+        If you wish to apply your transform on each cell, you might want to 
+        overwrite cell_transform method instead.
+        
+        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 not self.enabled :
-            return nb, other
+            return nb, resources
         else :
-            return super(ActivatableTransformer, self).__call__(nb, other)
+            return super(ActivatableTransformer, self).__call__(nb, resources)

nbconvert/transformers/base.py

@@ -1,59 +1,99 b''
 """
-Module that regroups transformer that woudl be applied to ipynb files
+Module that re-groups transformer that would be applied to iPyNB files
 before going through the templating machinery.
 
-It exposes convenient classes to inherit from to access configurability
-as well as decorator to simplify tasks.
+It exposes a convenient class to inherit from to access configurability.
 """
+#-----------------------------------------------------------------------------
+# Copyright (c) 2013, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
 
 from __future__ import print_function, absolute_import
 
 from IPython.config.configurable import Configurable
 
+#-----------------------------------------------------------------------------
+# Classes and Functions
+#-----------------------------------------------------------------------------
+
 class ConfigurableTransformer(Configurable):
     """ A configurable transformer
 
     Inherit from this class if you wish to have configurability for your
     transformer.
 
     Any configurable traitlets this class exposed will be configurable in profiles
     using c.SubClassName.atribute=value
 
     you can overwrite cell_transform to apply a transformation independently on each cell
     or __call__ if you prefer your own logic. See orresponding docstring for informations.
-
-
     """
 
     def __init__(self, config=None, **kw):
-        super(ConfigurableTransformer, self).__init__(config=config, **kw)
-
-    def __call__(self, nb, other):
-        """transformation to apply on each notebook.
+        """
+        Public constructor
+        
+        Parameters
+        ----------
+        config : Config
+            Configuration file structure
+        **kw : misc
+            Additional arguments
+        """
 
-        received a handle to the current notebook as well as a dict of resources
-        which structure depends on the transformer.
+        super(ConfigurableTransformer, self).__init__(config=config, **kw)
 
-        You should return modified nb, other.
 
-        If you wish to apply on each cell, you might want to overwrite cell_transform method.
+    def __call__(self, nb, resources):
+        """
+        Transformation to apply on each notebook.
+        
+        You should return modified nb, resources.
+        If you wish to apply your transform on each cell, you might want to 
+        overwrite cell_transform method instead.
+        
+        Parameters
+        ----------
+        nb : NotebookNode
+            Notebook being converted
+        resources : dictionary
+            Additional resources used in the conversion process.  Allows
+            transformers to pass variables into the Jinja engine.
         """
         try :
             for worksheet in nb.worksheets :
                 for index, cell in enumerate(worksheet.cells):
-                    worksheet.cells[index], other = self.cell_transform(cell, other, 100*index)
-            return nb, other
+                    
+                    #TODO: Why are we multiplying the index by 100 here???
+                    worksheet.cells[index], resources = self.cell_transform(cell, resources, 100*index)
+            return nb, resources
         except NotImplementedError:
             raise NotImplementedError('should be implemented by subclass')
 
-    def cell_transform(self, cell, other, index):
-        """
-        Overwrite if you want to apply a transformation on each cell,
-
-        receive the current cell, the resource dict and the index of current cell as parameter.
 
-        You should return modified cell and resource dict.
+    def cell_transform(self, cell, resources, index):
+        """
+        Overwrite if you want to apply a transformation on each cell.  You 
+        should return modified cell and resource dictionary.
+        
+        Parameters
+        ----------
+        cell : NotebookNode cell
+            Notebook cell being processed
+        resources : dictionary
+            Additional resources used in the conversion process.  Allows
+            transformers to pass variables into the Jinja engine.
+        index : int
+            Index of the cell being processed
         """
 
         raise NotImplementedError('should be implemented by subclass')
-        return cell, other
+        return cell, resources

nbconvert/transformers/coalescestreams.py

@@ -1,42 +1,75 b''
+"""Module that allows latex output notebooks to be conditioned before
+they are converted.  Exposes a decorator (@cell_preprocessor) in
+addition to the coalesce_streams pre-proccessor.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2013, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Functions
+#-----------------------------------------------------------------------------
 
 def cell_preprocessor(function):
-    """ wrap a function to be executed on all cells of a notebook
+    """
+    Wrap a function to be executed on all cells of a notebook
 
-wrapped function parameters :
-cell : the cell
-other : external resources
-index : index of the cell
+    Wrapped Parameters
+    ----------
+    cell : NotebookNode cell
+        Notebook cell being processed
+    resources : dictionary
+        Additional resources used in the conversion process.  Allows
+        transformers to pass variables into the Jinja engine.
+    index : int
+        Index of the cell being processed
 """
-    def wrappedfunc(nb, other):
+    
+    def wrappedfunc(nb, resources):
         for worksheet in nb.worksheets :
             for index, cell in enumerate(worksheet.cells):
-                worksheet.cells[index], other = function(cell, other, index)
-        return nb, other
+                worksheet.cells[index], resources = function(cell, resources, index)
+        return nb, resources
     return wrappedfunc
 
 
 @cell_preprocessor
-def coalesce_streams(cell, other, count):
-    """merge consecutive sequences of stream output into single stream
-
+def coalesce_streams(cell, resources, index):
+    """
+    Merge consecutive sequences of stream output into single stream
 to prevent extra newlines inserted at flush calls
 
-TODO: handle \r deletion
+    Parameters
+    ----------
+    cell : NotebookNode cell
+        Notebook cell being processed
+    resources : dictionary
+        Additional resources used in the conversion process.  Allows
+        transformers to pass variables into the Jinja engine.
+    index : int
+        Index of the cell being processed
 """
+    
     outputs = cell.get('outputs', [])
     if not outputs:
-        return cell, other
+        return cell, resources
+    
     last = outputs[0]
     new_outputs = [last]
+    
     for output in outputs[1:]:
         if (output.output_type == 'stream' and
             last.output_type == 'stream' and
             last.stream == output.stream
         ):
             last.text += output.text
         else:
             new_outputs.append(output)
 
     cell.outputs = new_outputs
-    return cell, other
+    return cell, resources
 

nbconvert/transformers/csshtmlheader.py

@@ -1,57 +1,119 b''
+"""Module that pre-processes the notebook for export to HTML.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2013, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+import os
+import io
+
+from pygments.formatters import HtmlFormatter
+        
+from IPython.utils import path
+
 from .activatable import ActivatableTransformer
 
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
 class CSSHtmlHeaderTransformer(ActivatableTransformer):
+    """
+    Transformer used to pre-process notebook for HTML output.  Adds IPython notebook
+    front-end CSS and Pygments CSS to HTML output.
+    """
+
+    header = []
+
+    def __init__(self, config=None, **kw):
+        """
+        Public constructor
+        
+        Parameters
+        ----------
+        config : Config
+            Configuration file structure
+        **kw : misc
+            Additional arguments
+        """
+        
+        super(CSSHtmlHeaderTransformer, self).__init__(config=config, **kw)
+
+        if self.enabled :
+            self._regen_header()
+
 
     def __call__(self, nb, resources):
-        """Fetch and add css to the resource dict
+        """Fetch and add CSS to the resource dictionary
 
-        Fetch css from IPython adn Pygment to add at the beginning
-        of the html files.
+        Fetch CSS from IPython and Pygments to add at the beginning
+        of the html files.  Add this css in resources in the 
+        "inlining.css" key
 
-        Add this css in resources in the "inlining.css" key
+        Parameters
+        ----------
+        nb : NotebookNode
+            Notebook being converted
+        resources : dictionary
+            Additional resources used in the conversion process.  Allows
+            transformers to pass variables into the Jinja engine.
         """
+        
         resources['inlining'] = {}
         resources['inlining']['css'] = self.header
+        
         return nb, resources
 
-    header = []
 
-    def __init__(self, config=None, **kw):
-        super(CSSHtmlHeaderTransformer, self).__init__(config=config, **kw)
-        if self.enabled :
-            self.regen_header()
+    def _regen_header(self):
+        """ 
+        Fills self.header with lines of CSS extracted from iPython 
+        and Pygments.
+        """
 
-    def regen_header(self):
-        ## lazy load asa this might not be use in many transformers
-        import os
-        from IPython.utils import path
-        import io
-        from pygments.formatters import HtmlFormatter
+        #Clear existing header.
         header = []
-        static = os.path.join(path.get_ipython_package_dir(),
-            'frontend', 'html', 'notebook', 'static',
-        )
+        
+        #Construct path to iPy CSS
+        static = os.path.join(path.get_ipython_package_dir(), 'frontend', 
+            'html', 'notebook', 'static')
         css = os.path.join(static, 'css')
+        
+        #Load each known CSS file.
         for sheet in [
-            # do we need jquery and prettify?
+            # TODO: do we need jquery and prettify?
             # os.path.join(static, 'jquery', 'css', 'themes', 'base',
             # 'jquery-ui.min.css'),
             # os.path.join(static, 'prettify', 'prettify.css'),
+            
             os.path.join(css, 'boilerplate.css'),
             os.path.join(css, 'fbm.css'),
             os.path.join(css, 'notebook.css'),
             os.path.join(css, 'renderedhtml.css'),
             os.path.join(css, 'style.min.css'),
         ]:
+            
             try:
-                with io.open(sheet, encoding='utf-8') as f:
-                    s = f.read()
-                    header.append(s)
+                with io.open(sheet, encoding='utf-8') as file:
+                    file_text = file.read()
+                    header.append(file_text)
             except IOError:
-                # new version of ipython with style.min.css, pass
+                
+                # New version of iPython with style.min.css, pass
                 pass
 
+        #Add pygments CSS
         pygments_css = HtmlFormatter().get_style_defs('.highlight')
         header.append(pygments_css)
+
+        #Set header        
         self.header = header
 

nbconvert/transformers/extractfigure.py

@@ -1,66 +1,127 b''
+"""Module containing a transformer that extracts all of the figures from the
+notebook file.  The extracted figures are returned in the 'resources' dictionary.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2013, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
 from IPython.utils.traitlets import (Dict, List, Unicode)
 from .activatable import ActivatableTransformer
 
-class ExtractFigureTransformer(ActivatableTransformer):
+#-----------------------------------------------------------------------------
+# Constants
+#-----------------------------------------------------------------------------
 
+FIGURES_KEY = "figures"
+BINARY_KEY = "binary"
+TEXT_KEY = "text"
 
-    extra_ext_map =  Dict({},
-            config=True,
-            help="""extra map to override extension based on type.
-            Usefull for latex where svg will be converted to pdf before inclusion
+#-----------------------------------------------------------------------------
+# Classes
+#-----------------------------------------------------------------------------
+
+class ExtractFigureTransformer(ActivatableTransformer):
+    """
+    Extracts all of the figures from the notebook file.  The extracted 
+    figures are returned in the 'resources' dictionary.
             """
-            )
 
-    key_format_map =  Dict({},
+    extra_extension_map =  Dict({},
             config=True,
-            )
+        help="""Extra map to override extension based on type.
+        Useful for latex where SVG will be converted to PDF before inclusion
+        """)
 
-    figname_format_map =  Dict({},
-            config=True,
-            )
+    key_format_map =  Dict({}, config=True,)
+    figure_name_format_map =  Dict({}, config=True)
 
     display_data_priority = List(['svg', 'png', 'latex', 'jpg', 'jpeg','text'])
 
-    #to do change this to .format {} syntax
-    default_key_tpl = Unicode('_fig_{count:02d}.{ext}', config=True)
+    #TODO: Change this to .format {} syntax
+    default_key_template = Unicode('_fig_{count:02d}.{ext}', config=True)
+
+    def cell_transform(self, cell, resources, index):
+        """
+        Apply a transformation on each cell,
+        
+        Parameters
+        ----------
+        cell : NotebookNode cell
+            Notebook cell being processed
+        resources : dictionary
+            Additional resources used in the conversion process.  Allows
+            transformers to pass variables into the Jinja engine.
+        index : int
+            Modified index of the cell being processed (see base.py)
+        """
+        
+        if resources.get(FIGURES_KEY, None) is None :
+            resources[FIGURES_KEY] = {TEXT_KEY:{},BINARY_KEY:{}}
+            
+        for out in cell.get('outputs', []):
+            for out_type in self.display_data_priority:
+                
+                if out.hasattr(out_type):
+                    figname, key, data, binary = self._new_figure(out[out_type], out_type, index)
+                    out['key_'+out_type] = figname
+                    
+                    if binary :
+                        resources[FIGURES_KEY][BINARY_KEY][key] = data
+                    else :
+                        resources[FIGURES_KEY][TEXT_KEY][key] = data
+                        
+                    index += 1
+        return cell, resources
+
+
+    def _get_override_extension(self, extension):
+        """Gets the overriden extension if it exists, else returns extension. 
 
-    def _get_ext(self, ext):
-        if ext in self.extra_ext_map :
-            return self.extra_ext_map[ext]
-        return ext
+        Parameters
+        ----------
+        extension : str
+            File extension.
+        """
+        
+        if extension in self.extra_extension_map :
+            return self.extra_extension_map[extension]
+    
+        return extension
 
-    def _new_figure(self, data, fmt, count):
+
+    def _new_figure(self, data, format, index):
         """Create a new figure file in the given format.
 
+        Parameters
+        ----------
+        data : str
+            Cell data (from Notebook node cell)
+        resources : dictionary
+            Additional resources used in the conversion process.  Allows
+            transformers to pass variables into the Jinja engine.
+        index : int
+            Modified index of the cell being processed (see base.py)
         """
-        tplf = self.figname_format_map.get(fmt, self.default_key_tpl)
-        tplk = self.key_format_map.get(fmt, self.default_key_tpl)
 
-        # option to pass the hash as data ?
-        figname = tplf.format(count=count, ext=self._get_ext(fmt))
-        key     = tplk.format(count=count, ext=self._get_ext(fmt))
+        figure_name_template = self.figure_name_format_map.get(format, self.default_key_template)
+        key_template = self.key_format_map.get(format, self.default_key_template)
+
+        #TODO: option to pass the hash as data?
+        figure_name = figure_name_template.format(index=index, ext=self._get_override_extension(format))
+        key = key_template.format(index=index, ext=self._get_override_extension(format))
 
         # Binary files are base64-encoded, SVG is already XML
         binary = False
-        if fmt in ('png', 'jpg', 'pdf'):
+        if format in ('png', 'jpg', 'pdf'):
             data = data.decode('base64')
             binary = True
 
-        return figname, key, data, binary
-
-
-    def cell_transform(self, cell, other, count):
-        if other.get('figures', None) is None :
-            other['figures'] = {'text':{},'binary':{}}
-        for out in cell.get('outputs', []):
-            for out_type in self.display_data_priority:
-                if out.hasattr(out_type):
-                    figname, key, data, binary = self._new_figure(out[out_type], out_type, count)
-                    out['key_'+out_type] = figname
-                    if binary :
-                        other['figures']['binary'][key] = data
-                    else :
-                        other['figures']['text'][key] = data
-                    count = count+1
-        return cell, other
-
+        return figure_name, key, data, binary

nbconvert/transformers/latex.py

@@ -1,43 +1,53 b''
-"""Latex transformer.
-
-Module that allows latex output notebooks to be conditioned before
+"""Module that allows latex output notebooks to be conditioned before
 they are converted.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
+
 from __future__ import print_function, absolute_import
 
 # Our own imports
 # Needed to override transformer
 from .activatable import (ActivatableTransformer)
 from nbconvert.filters import latex
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
+
 class LatexTransformer(ActivatableTransformer):
     """
     Converter for latex destined documents.
     """
 
-    def cell_transform(self, cell, other, index):
+    def cell_transform(self, cell, resources, index):
         """
         Apply a transformation on each cell,
 
-        receive the current cell, the resource dict and the index of current cell as parameter.
-
-        Returns modified cell and resource dict.
+        Parameters
+        ----------
+        cell : NotebookNode cell
+            Notebook cell being processed
+        resources : dictionary
+            Additional resources used in the conversion process.  Allows
+            transformers to pass variables into the Jinja engine.
+        index : int
+            Modified index of the cell being processed (see base.py)
         """
         
+        #If the cell is a markdown cell, preprocess the ampersands used to
+        #remove the space between them and their contents.  Latex will complain
+        #if spaces exist between the ampersands and the math content.  
+        #See filters.latex.rm_math_space for more information.
         if hasattr(cell, "source") and cell.cell_type == "markdown":
             cell.source = latex.rm_math_space(cell.source)
-        return cell, other
+        return cell, resources

nbconvert/transformers/revealhelp.py

@@ -1,17 +1,55 b''
+"""Module that pre-processes the notebook for export via Reveal.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2013, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
 from .base import ConfigurableTransformer
 
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
 class RevealHelpTransformer(ConfigurableTransformer):
 
-    def __call__(self, nb, other):
+    def __call__(self, nb, resources):
+        """
+        Called once to 'transform' contents of the notebook.
+        
+        Parameters
+        ----------
+        nb : NotebookNode
+            Notebook being converted
+        resources : dictionary
+            Additional resources used in the conversion process.  Allows
+            transformers to pass variables into the Jinja engine.
+        """
+        
+        
         for worksheet in nb.worksheets :
             for i, cell in enumerate(worksheet.cells):
+                
+                #Make sure the cell has metadata.
                 if not cell.get('metadata', None):
                     break
+                
+                #Get the slide type.  If type is start of subslide or slide,
+                #end the last subslide/slide.
                 cell.metadata.slide_type = cell.metadata.get('slideshow', {}).get('slide_type', None)
                 if cell.metadata.slide_type is None:
                     cell.metadata.slide_type = '-'
                 if cell.metadata.slide_type in ['slide']:
                     worksheet.cells[i - 1].metadata.slide_helper = 'slide_end'
                 if cell.metadata.slide_type in ['subslide']:
                     worksheet.cells[i - 1].metadata.slide_helper = 'subslide_end'
-        return nb, other
  No newline at end of file
+                    
+        return nb, resources
+    
  No newline at end of file

nbconvert/transformers/sphinx.py

@@ -1,287 +1,282 b''
 """Module that allows custom Sphinx parameters to be set on the notebook and
-on the 'other' object passed into Jinja.
+on the 'other' object passed into Jinja.  Called prior to Jinja conversion
+process.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
+
 from __future__ import print_function, absolute_import
 
 # Stdlib imports
 # Used to find Sphinx package location
 import sphinx
 import os.path
 
-# Used to determine python version
-import sys
-
 # Used to set the default date to today's date 
 from datetime import date 
 
 # Third-party imports
 # Needed for Pygments latex definitions.
 from pygments.formatters import LatexFormatter
 
 # Our own imports
 # Configurable traitlets
 from IPython.utils.traitlets import Unicode, Bool
 
 # Needed to override transformer
 from .activatable import (ActivatableTransformer) #TODO
 
+import nbconvert.utils.console  
+
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
+
 class SphinxTransformer(ActivatableTransformer):
     """
     Sphinx utility transformer.
 
     This transformer is used to set variables needed by the latex to build
     Sphinx stylized templates.
     """
     
     interactive = Bool(True, config=True, help="""
     Allows you to define whether or not the Sphinx exporter will prompt
     you for input during the conversion process.  If this is set to false,
     the author, version, release, date, and chapter_style traits should
     be set.
     """)
     
     author = Unicode("Unknown Author", config=True, help="Author name")
     
-    version = Unicode("", config=True, help="""Version number
+    version = Unicode("", config=True, help="""
+        Version number
     You can leave this blank if you do not want to render a version number.
     Example: "1.0.0"
     """)
     
-    release = Unicode("", config=True, help="""Release name
+    release = Unicode("", config=True, help="""
+        Release name
     You can leave this blank if you do not want to render a release name.
     Example: "Rough Draft"
     """)
     
-    publish_date = Unicode("", config=True, help="""Publish date
+    publish_date = Unicode("", config=True, help="""
+        Publish date
     This is the date to render on the document as the publish date.
     Leave this blank to default to todays date.  
     Example: "June 12, 1990"
     """)
     
-    chapter_style = Unicode("Bjarne", config=True, help="""Sphinx chapter style
+    chapter_style = Unicode("Bjarne", config=True, help="""
+        Sphinx chapter style
     This is the style to use for the chapter headers in the document.
     You may choose one of the following:
         "Bjarne"    (default)
         "Lenny"
         "Glenn"
         "Conny"
         "Rejne"
         "Sonny"    (used for international documents)
     """)
     
-    output_style = Unicode("notebook", config=True, help="""Nbconvert Ipython
+    output_style = Unicode("notebook", config=True, help="""
+        Nbconvert Ipython
     notebook input/output formatting style.
     You may choose one of the following:
         "simple     (recommended for long code segments)"
         "notebook"  (default)
     """)
     
     center_output = Bool(False, config=True, help="""
     Optional attempt to center all output.  If this is false, no additional
     formatting is applied.
     """)
     
     use_headers = Bool(True, config=True, help="""
     Whether not a header should be added to the document.
     """)
     
+    #Allow the user to override the title of the notebook (useful for
+    #fancy document titles that the file system doesn't support.)
     overridetitle = Unicode("", config=True, help="")
     
-    def __call__(self, nb, other):
+    
+    def __call__(self, nb, resources):
         """
-        Entry
+        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, other)
+            return self.transform(nb, resources)
         else:
-            return nb,other
+            return nb,resources
+
 
-    def transform(self, nb, other):
+    def transform(self, nb, resources):
         """
         Sphinx transformation to apply on each notebook.
+        
+        Parameters
+        ----------
+        nb : NotebookNode
+            Notebook being converted
+        resources : dictionary
+            Additional resources used in the conversion process.  Allows
+            transformers to pass variables into the Jinja engine.
         """
          
         # TODO: Add versatile method of additional notebook metadata.  Include
         #       handling of multiple files.  For now use a temporay namespace,
         #       '_draft' to signify that this needs to change.
         if not "_draft" in nb.metadata:
             nb.metadata._draft = {}
             
-        if not "sphinx" in other:
-            other["sphinx"] = {}
+        if not "sphinx" in resources:
+            resources["sphinx"] = {}
 
         if self.interactive:
             
             # Prompt the user for additional meta data that doesn't exist currently
             # but would be usefull for Sphinx.
             nb.metadata._draft["author"] = self._prompt_author()
             nb.metadata._draft["version"] = self._prompt_version()
             nb.metadata._draft["release"] = self._prompt_release()
             nb.metadata._draft["date"] = self._prompt_date()
             
             # Prompt the user for the document style.
-            other["sphinx"]["chapterstyle"] = self._prompt_chapter_title_style()
-            other["sphinx"]["outputstyle"] = self._prompt_output_style()
+            resources["sphinx"]["chapterstyle"] = self._prompt_chapter_title_style()
+            resources["sphinx"]["outputstyle"] = self._prompt_output_style()
             
             # Small options
-            other["sphinx"]["centeroutput"] = self._prompt_boolean("Do you want to center the output? (false)", False)
-            other["sphinx"]["header"] = self._prompt_boolean("Should a Sphinx document header be used? (true)", True)
+            resources["sphinx"]["centeroutput"] = nbconvert.utils.console.prompt_boolean("Do you want to center the output? (false)", False)
+            resources["sphinx"]["header"] = nbconvert.utils.console.prompt_boolean("Should a Sphinx document header be used? (true)", True)
         else:
             
             # Try to use the traitlets.
             nb.metadata._draft["author"] = self.author
             nb.metadata._draft["version"] = self.version
             nb.metadata._draft["release"] = self.release
             
             # Use todays date if none is provided.
             if len(self.publish_date.strip()) == 0:
                 nb.metadata._draft["date"] = date.today().strftime("%B %-d, %Y")
             else:
                 nb.metadata._draft["date"] = self.publish_date
             
             # Sphinx traitlets.
-            other["sphinx"]["chapterstyle"] = self.chapter_style
-            other["sphinx"]["outputstyle"] = self.output_style
-            other["sphinx"]["centeroutput"] = self.center_output
-            other["sphinx"]["header"] = self.use_headers
+            resources["sphinx"]["chapterstyle"] = self.chapter_style
+            resources["sphinx"]["outputstyle"] = self.output_style
+            resources["sphinx"]["centeroutput"] = self.center_output
+            resources["sphinx"]["header"] = self.use_headers
             
         # Find and pass in the path to the Sphinx dependencies.
-        other["sphinx"]["texinputs"] = os.path.abspath(sphinx.__file__ + "/../texinputs")
+        resources["sphinx"]["texinputs"] = os.path.abspath(sphinx.__file__ + "/../texinputs")
         
         # Generate Pygments definitions for Latex 
-        other["sphinx"]["pygment_definitions"] = self._generate_pygments_latex_def()
+        resources["sphinx"]["pygment_definitions"] = self._generate_pygments_latex_def()
         
         if not (self.overridetitle == None or len(self.overridetitle.strip()) == 0):
             nb.metadata.name = self.overridetitle
         
         # End
-        return nb, other 
+        return nb, resources 
+    
     
     def _generate_pygments_latex_def(self):
+        """
+        Generate the pygments latex definitions that allows pygments
+        to work in latex.
+        """
+        
         return LatexFormatter().get_style_defs()       
     
+    
     def _prompt_author(self):
-        return  self._input("Author name: ")
+        """
+        Prompt the user to input an Author name
+        """
+        return  nbconvert.utils.console.input("Author name: ")
+    
     
     def _prompt_version(self):
-        return  self._input("Version (ie ""1.0.0""): ")
+        """
+        prompt the user to enter a version number
+        """
+        return  nbconvert.utils.console.input("Version (ie ""1.0.0""): ")
+    
     
     def _prompt_release(self):
-        return  self._input("Release Name (ie ""Rough draft""): ")
+        """
+        Prompt the user to input a release name
+        """
+        
+        return  nbconvert.utils.console.input("Release Name (ie ""Rough draft""): ")
+    
     
     def _prompt_date(self):
+        """
+        Prompt the user to enter a date
+        """
+        
         default_date = date.today().strftime("%B %-d, %Y")
-        user_date = self._input("Date (deafults to \"" + default_date + "\"): ")
+        user_date = nbconvert.utils.console.input("Date (deafults to \"" + default_date + "\"): ")
         if len(user_date.strip()) == 0:
             user_date = default_date
         return user_date
     
-    def _prompt_boolean(self, prompt, default=False):
-        response = self._input(prompt)
-        response = response.strip().lower()
-        
-        #Catch 1, true, yes as True
-        if len(response) > 0 and (response == "1" or response[0] == "t" or response[0] == "y"):
-            return True
-        
-        #Catch 0, false, no as False
-        elif len(response) > 0 and (response == "0" or response[0] == "f" or response[0] == "n"):
-            return False
-            
-        else:
-            return default
         
     def _prompt_output_style(self):
+        """
+        Prompts the user to pick an iPython output style.
+        """
         
         # Dictionary of available output styles
         styles = {1: "simple",
                   2: "notebook"}
         
         #Append comments to the menu when displaying it to the user.
         comments = {1: "(recommended for long code segments)",
                     2: "(default)"}
         
-        return self._prompt_dictionary(styles, default_style=2, menu_comments=comments)
+        return nbconvert.utils.console.prompt_dictionary(styles, default_style=2, menu_comments=comments)
+    
     
     def _prompt_chapter_title_style(self):
+        """
+        Prompts the user to pick a Sphinx chapter style
+        """
         
         # Dictionary of available Sphinx styles
         styles = {1: "Bjarne",
                   2: "Lenny",
                   3: "Glenn",
                   4: "Conny",
                   5: "Rejne",
                   6: "Sonny"}
         
         #Append comments to the menu when displaying it to the user.
         comments = {1: "(default)",
                     6: "(for international documents)"}
         
-        return self._prompt_dictionary(styles, menu_comments=comments)
-    
-    def _prompt_dictionary(self, choices, default_style=1, menu_comments={}):
-                
-        # Build the menu that will be displayed to the user with
-        # all of the options available. 
-        prompt = ""
-        for key, value in choices.iteritems():
-            prompt += "%d %s " % (key, value)
-            if key in menu_comments:
-                prompt += menu_comments[key]
-            prompt += "\n"
-        
-        # Continue to ask the user for a style until an appropriate
-        # one is specified.
-        response = -1
-        while (not response in choices):
-            try:
-                text_response = self._input(prompt)
-                
-                # Use default option if no input.
-                if len(text_response.strip()) == 0:
-                    response = default_style
-                else:
-                    response = int(text_response)
-            except:
-                print("Error: Value is not an available option.  0 selects the default.\n")
-        return choices[response]
-          
-    def _input(self, prompt_text):
-        """
-        Prompt the user for input.
+        return nbconvert.utils.console.prompt_dictionary(styles, menu_comments=comments)
         
  No newline at end of file
-        The input command will change depending on the version of python
-        installed.  To maintain support for 2 and earlier, we must use
-        raw_input in that case.  Else use input.
-        """
-        
-        # Try to get the python version.  This command is only available in
-        # python 2 and later, so it's important that we catch the exception
-        # if the command isn't found.
-        try:
-            majorversion = sys.version_info[0]
-        except:
-            majorversion = 1
-            
-        # Use the correct function to prompt the user for input depending on 
-        # what python version the code is running in.
-        if majorversion >= 3:
-            return input(prompt_text) 
-        else:
-            return raw_input(prompt_text)