Finished rename/refact on API namespace

nbconvert/api/basichtml.py

@@ -1,52 +1,55 b''
 """
 Exporter that exports Basic 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
 #-----------------------------------------------------------------------------
 
 from IPython.utils.traitlets import Unicode
 
 import nbconvert.transformers.csshtmlheader
 
 # local import
 import exporter
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class BasicHtmlExporter(exporter.Exporter):
     """
     Exports a basic HTML document.  This exporter assists with the export of
     HTML.  Inherit from it if you are writing your own HTML template and need
     custom tranformers/filters.  If you don't need custom tranformers/
     filters, just change the 'template_file' config option.  
     """
     
     file_extension = Unicode(
         'html', config=True, 
         help="Extension of the file that should be written to disk"
         )
 
     template_file = Unicode(
             'basichtml', config=True,
             help="Name of the template file to use")
 
     def _register_transformers(self):
+        """
+        Register all of the transformers needed for this exporter.
+        """
         
         #Register the transformers of the base class.
         super(BasicHtmlExporter, self)._register_transformers()
         
         #Register latex transformer
         self.register_transformer(nbconvert.transformers.csshtmlheader.CSSHtmlHeaderTransformer)
                     
  No newline at end of file

nbconvert/api/convert.py

@@ -1,51 +1,483 b''
 """
-Module containing easy to use conversion functions.
+Module containing single call export functions.
 """
 #-----------------------------------------------------------------------------
 # 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 sys
+import inspect
+
 from .exporter import Exporter
 
 from IPython.nbformat.v3.nbbase import NotebookNode
 
+from .fullhtml import FullHtmlExporter
+from .basichtml import BasicHtmlExporter
+from .latex import LatexExporter
+from .markdown import MarkdownExporter
+from .python import PythonExporter
+from .python_armor import PythonArmorExporter
+from .reveal import RevealExporter
+from .rst import RstExporter
+from .sphinx_howto import SphinxHowtoExporter
+from .sphinx_manual import SphinxManualExporter
+
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
 
 def export(nb, config=None, transformers=None, filters=None, exporter_type=Exporter):
+    """
+    Export a notebook object using specific exporter class.
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+    exporter_type:
+        Class type of the exporter that should be used.  This method
+        will initialize it's own instance of the class.  It is
+        ASSUMED that the class type provided exposes a
+        constructor (__init__) with the same signature as the
+        base Exporter class.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
     
     #Check arguments
     if exporter_type is None:
         raise TypeError("Exporter is None")
     elif not issubclass(exporter_type, Exporter):
         raise TypeError("Exporter type does not inherit from Exporter (base)")
     
     if nb is None:
         raise TypeError("nb is None")
     
     #Create the exporter
-    exporter_instance = exporter_type(preprocessors=transformers, jinja_filters=filters, config=config)
+    exporter_instance = exporter_type(preprocessors=transformers, 
+                                      jinja_filters=filters, config=config)
 
     #Try to convert the notebook using the appropriate conversion function.
     if isinstance(nb, NotebookNode):
         output, resources = exporter_instance.from_notebook_node(nb)
     elif isinstance(nb, basestring):
         output, resources = exporter_instance.from_filename(nb)
     else:
         output, resources = exporter_instance.from_file(nb)
     return output, resources, exporter_instance
 
 
-def load_class(template_name):
-    class_name = template_name[0].upper() + template_name[1:] + "Exporter"
-    module = __import__('nbconvert.api.' + template_name, fromlist=[class_name])                                       
-    return getattr(module, class_name)
+def export_sphinx_manual(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to Sphinx Manual LaTeX
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, SphinxManualExporter)
+
+
+def export_sphinx_howto(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to Sphinx HowTo LaTeX
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, SphinxHowtoExporter)
+
+
+def export_basic_html(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to Basic HTML
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, BasicHtmlExporter)
+
+
+def export_full_html(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to Full HTML
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, FullHtmlExporter)
+
+
+def export_latex(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to LaTeX
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, LatexExporter)
+
+
+def export_markdown(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to Markdown
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, MarkdownExporter)
+
+
+def export_python(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to Python
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, PythonExporter)
+
+
+def export_python_armor(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to Python (Armor)
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, PythonArmorExporter)
+
+
+def export_reveal(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to Reveal
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, RevealExporter)
+
+
+def export_rst(nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object to RST
+    
+    Parameters
+    ----------
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    return export(nb, config, transformers, filters, RstExporter)
 
 
 def export_by_name(nb, template_name, config=None, transformers=None, filters=None):
-    return export(nb, config, transformers, filters, load_class(template_name))
  No newline at end of file
+    """
+    Export a notebook object to a template type by its name.  Reflection
+    (Inspect) is used to find the template's corresponding explicit export
+    method defined in this module.  That method is then called directly.
+    
+    Parameters
+    ----------
+    template_name : str
+        Name of the template style to export to.
+    config : config
+        User configuration instance.
+    transformers : list[of transformer]
+        Custom transformers to apply to the notebook prior to engaging
+        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.
+        
+    Returns
+    ----------
+    tuple- output, resources, exporter_instance
+    output : str
+        Jinja 2 output.  This is the resulting converted notebook.
+    resources : dictionary
+        Dictionary of resources used prior to and during the conversion 
+        process.
+    exporter_instance : Exporter
+        Instance of the Exporter class used to export the document.  Useful
+        to caller because it provides a 'file_extension' property which
+        specifies what extension the output should be saved as.
+    """
+    
+    #Use reflection to get functions defined in this module.
+    cls_functions = inspect.getmembers(sys.modules[__name__], inspect.isfunction)
+    
+    #Check if the characters following "export_" (7 char) equals the template name.
+    for function in cls_functions:
+        function_name = function.__name__.lower() 
+        if (len(function_name) > 7 and function_name[7:] == template_name.lower()):
+            return function(nb, config, transformers, filters)
+            
  No newline at end of file

nbconvert/api/exporter.py

@@ -1,205 +1,316 b''
-"""Exporter for the notebook conversion pipeline.
-
-This module defines Exporter, a highly configurable converter
-that uses Jinja2 to export notebook files into different format.
-
-You can register both pre-transformers that will act on the notebook format
-before conversion and jinja filter that would then be available in the templates
+"""This module defines Exporter, a highly configurable converter
+that uses Jinja2 to export notebook files into different formats.
 """
 
 #-----------------------------------------------------------------------------
 # 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
 import io
 import os
 import inspect
 
 # IPython imports
 from IPython.config.configurable import Configurable
 from IPython.nbformat import current as nbformat
 from IPython.utils.traitlets import MetaHasTraits, Unicode, List, Bool
 from IPython.utils.text import indent
 
 # other libs/dependencies
 from jinja2 import Environment, FileSystemLoader
 from markdown import markdown
 
 # local import
 import nbconvert.filters.strings
 import nbconvert.filters.markdown
 import nbconvert.filters.latex
 import nbconvert.filters.datatypefilter
 import nbconvert.filters.highlight
 import nbconvert.filters.ansi
 
 import nbconvert.transformers.extractfigure
 import nbconvert.transformers.coalescestreams
 
-
 #-----------------------------------------------------------------------------
 # Globals and constants
 #-----------------------------------------------------------------------------
 
-#Standard Jinja2 environment constants
-TEMPLATE_PATH = "/../templates/"
-TEMPLATE_SKELETON_PATH = "/../templates/skeleton/"
-
 #Jinja2 extensions to load.
 JINJA_EXTENSIONS = ['jinja2.ext.loopcontrols']
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class Exporter(Configurable):
-
+    """
+    Exports notebooks into other file formats.  Uses Jinja 2 templating engine
+    to output new formats.  Inherit from this class if you are creating a new
+    template type along with new filters/transformers.  If the filters/
+    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.
+    """
+    
     template_file = Unicode(
             '', config=True,
             help="Name of the template file to use")
 
     file_extension = Unicode(
         'txt', config=True, 
         help="Extension of the file that should be written to disk"
         )
 
+    template_path = Unicode(
+        "/../templates/", config=True,
+        help="Path where the template files are located.")
+
+    template_skeleton_path = Unicode(
+        "/../templates/skeleton/", config=True,
+        help="Path where the template skeleton files are located.") 
+
+    #Jinja block definitions
+    jinja_comment_block_start = Unicode(None, config=True)
+    jinja_comment_block_end = Unicode(None, config=True)
+    jinja_variable_block_start = Unicode(None, config=True)
+    jinja_variable_block_end = Unicode(None, config=True)
+    jinja_logic_block_start = Unicode(None, config=True)
+    jinja_logic_block_end = Unicode(None, config=True)
+    
     #Extension that the template files use.    
-    template_extension = ".tpl"
+    template_extension = Unicode(".tpl", config=True)
 
     #Processors that process the input data prior to the export, set in the 
     #constructor for this class.
     preprocessors = [] 
 
-    # Public Constructor #####################################################
     
     def __init__(self, transformers=None, filters=None, config=None, **kw):
+        """
+        Public constructor
     
+        Parameters
+        ----------
+        transformers : list[of transformer]
+            Custom transformers to apply to the notebook prior to engaging
+            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.
+        config : config
+            User configuration instance.
+        """
+        
         #Call the base class constructor
         super(Exporter, self).__init__(config=config, **kw)
 
         #Standard environment
         self._init_environment()
 
         #Add transformers
         self._register_transformers()
 
         #Add filters to the Jinja2 environment
         self._register_filters()
 
         #Load user transformers.  Overwrite existing transformers if need be.
         if not transformers is None:        
             for transformer in transformers:
                 self.register_transformer(transformer)
                 
         #Load user filters.  Overwrite existing filters if need be.
         if not filters is None:
             for key, user_filter in filters.iteritems():
                 if issubclass(user_filter, MetaHasTraits):
                     self.environment.filters[key] = user_filter(config=config)
                 else:
                     self.environment.filters[key] = user_filter
     
-    # Public methods #########################################
     
     def from_notebook_node(self, nb):
+        """
+        Convert a notebook from a notebook node instance.
+    
+        Parameters
+        ----------
+        nb : Notebook node
+        """
+        
         nb, resources = self._preprocess(nb)
         
         #Load the template file.
         self.template = self.environment.get_template(self.template_file+self.template_extension)
         
         return self.template.render(nb=nb, resources=resources), resources
 
 
     def from_filename(self, filename):
+        """
+        Convert a notebook from a notebook file.
+    
+        Parameters
+        ----------
+        filename : str
+            Full filename of the notebook file to open and convert.
+        """
+        
         with io.open(filename) as f:
             return self.from_notebook_node(nbformat.read(f, 'json'))
 
 
     def from_file(self, file_stream):
+        """
+        Convert a notebook from a notebook file.
+    
+        Parameters
+        ----------
+        file_stream : file-like object
+            Notebook file-like object to convert.
+        """
         return self.from_notebook_node(nbformat.read(file_stream, 'json'))
 
 
     def register_transformer(self, transformer):
+        """
+        Register a transformer.
+        Transformers are classes that act upon the notebook before it is
+        passed into the Jinja templating engine.  Transformers are also
+        capable of passing additional information to the Jinja
+        templating engine.
+    
+        Parameters
+        ----------
+        transformer : transformer
+        """
+        
         if inspect.isfunction(transformer):
             self.preprocessors.append(transformer)
             return transformer
         elif isinstance(transformer, MetaHasTraits):
             transformer_instance = transformer(config=self.config)
             self.preprocessors.append(transformer_instance)
             return transformer_instance
         else:
             transformer_instance = transformer()
             self.preprocessors.append(transformer_instance)
             return transformer_instance
 
 
     def register_filter(self, name, filter):
+        """
+        Register a filter.
+        A filter is a function that accepts and acts on one string.  
+        The filters are accesible within the Jinja templating engine.
+    
+        Parameters
+        ----------
+        name : str
+            name to give the filter in the Jinja engine
+        filter : filter
+        """
+        
         if inspect.isfunction(filter):
             self.environment.filters[name] = filter
         elif isinstance(filter, MetaHasTraits):
             self.environment.filters[name] = filter(config=self.config)
         else:
             self.environment.filters[name] = filter()
         return self.environment.filters[name]
 
-
-    # Protected and Private methods #########################################
     
     def _register_transformers(self):
+        """
+        Register all of the transformers needed for this exporter.
+        """
+        
         self.register_transformer(nbconvert.transformers.coalescestreams.coalesce_streams)
         
         #Remember the figure extraction transformer so it can be enabled and
         #disabled easily later.
         self.extract_figure_transformer = self.register_transformer(nbconvert.transformers.extractfigure.ExtractFigureTransformer)
         
         
     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)
         
         
     def _init_environment(self):
+        """
+        Create the Jinja templating environment.
+        """
+        
         self.environment = Environment(
             loader=FileSystemLoader([
-                os.path.dirname(os.path.realpath(__file__)) + TEMPLATE_PATH,
-                os.path.dirname(os.path.realpath(__file__)) + TEMPLATE_SKELETON_PATH,
+                os.path.dirname(os.path.realpath(__file__)) + self.template_path,
+                os.path.dirname(os.path.realpath(__file__)) + self.template_skeleton_path,
                 ]),
             extensions=JINJA_EXTENSIONS
             )
+        
+        #Set special Jinja2 syntax that will not conflict with latex.
+        if not self.jinja_logic_block_start == None:
+            self.environment.block_start_string = self.jinja_logic_block_start
+        if not self.jinja_logic_block_end == None:
+            self.environment.block_end_string = self.jinja_logic_block_end
+        if not self.jinja_variable_block_start == None:
+            self.environment.variable_start_string = self.jinja_variable_block_start
+        if not self.jinja_variable_block_end == None:
+            self.environment.variable_end_string = self.jinja_variable_block_end
+        if not self.jinja_comment_block_start == None:
+            self.environment.comment_start_string = self.jinja_comment_block_start
+        if not self.jinja_comment_block_end == None:
+            self.environment.comment_end_string = self.jinja_comment_block_end
 
 
     def _preprocess(self, nb):
-
+        """
+        Preprocess the notebook before passing it into the Jinja engine.
+        To preprocess the notebook is to apply all of the 
+    
+        Parameters
+        ----------
+        nb : notebook node
+            notebook that is being exported.
+        """
+        
         #Dict of 'resources' that can be filled by the preprocessors.
         resources = {}
 
         #Run each transformer on the notebook.  Carry the output along
         #to each transformer
         for transformer in self.preprocessors:
             nb, resources = transformer(nb, resources)
         return nb, resources

nbconvert/api/latex.py

@@ -1,117 +1,126 b''
 """
 Exporter that allows Latex Jinja templates to work.  Contains logic to
 appropriately prepare IPYNB files for export to LaTeX.  Including but 
 not limited to escaping LaTeX, fixing math region tags, using special
 tags to circumvent Jinja/Latex syntax conflicts.
 """
 #-----------------------------------------------------------------------------
 # 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
 #-----------------------------------------------------------------------------
 
 # Stdlib imports
 import os
 
 # IPython imports
 from IPython.utils.traitlets import Unicode
 
 # other libs/dependencies
 from jinja2 import Environment, FileSystemLoader
 
 import nbconvert.filters.latex
 import nbconvert.filters.highlight
 from nbconvert.transformers.latex import LatexTransformer
 
 # local import
 import exporter
 
 #-----------------------------------------------------------------------------
-# Globals and constants
-#-----------------------------------------------------------------------------
-
-#Latex Jinja2 constants
-LATEX_TEMPLATE_PATH = "/../templates/latex/"
-LATEX_TEMPLATE_SKELETON_PATH = "/../templates/latex/skeleton/"
-
-#Special Jinja2 syntax that will not conflict when exporting latex.
-LATEX_JINJA_COMMENT_BLOCK = ["((=", "=))"]
-LATEX_JINJA_VARIABLE_BLOCK = ["(((", ")))"]
-LATEX_JINJA_LOGIC_BLOCK = ["((*", "*))"]
-
-#-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class LatexExporter(exporter.Exporter):
     """
     Exports to a Latex template.  Inherit from this class if your template is
     LaTeX based and you need custom tranformers/filters.  Inherit from it if 
     you are writing your own HTML template and need custom tranformers/filters.  
     If you don't need custom tranformers/filters, just change the 
     'template_file' config option.  Place your template in the special "/latex" 
     subfolder of the "../templates" folder.
     """
     
-    #Extension that the template files use.    
-    template_extension = ".tplx"
-    
     file_extension = Unicode(
         'tex', config=True, 
         help="Extension of the file that should be written to disk")
 
     template_file = Unicode(
-            'base', config=True,
-            help="Name of the template file to use")
+        'base', config=True,
+        help="Name of the template file to use")
+
+    #Latex constants
+    template_path = Unicode(
+        "/../templates/latex/", config=True,
+        help="Path where the template files are located.")
+
+    template_skeleton_path = Unicode(
+        "/../templates/latex/skeleton/", config=True,
+        help="Path where the template skeleton files are located.") 
+
+    #Special Jinja2 syntax that will not conflict when exporting latex.
+    jinja_comment_block_start = Unicode("((=", config=True)
+    jinja_comment_block_end = Unicode("=))", config=True)
+    jinja_variable_block_start = Unicode("(((", config=True)
+    jinja_variable_block_end = Unicode(")))", config=True)
+    jinja_logic_block_start = Unicode("((*", config=True)
+    jinja_logic_block_end = Unicode("*))", config=True)
+    
+    #Extension that the template files use.    
+    template_extension = Unicode(".tplx", config=True)
     
     def __init__(self, transformers=None, filters=None, config=None, **kw):
+        """
+        Public constructor
+    
+        Parameters
+        ----------
+        transformers : list[of transformer]
+            Custom transformers to apply to the notebook prior to engaging
+            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.
+        config : config
+            User configuration instance.
+        """
         
         #Call base class constructor.
         super(LatexExporter, self).__init__(transformers, filters, config, **kw)
         
         self.extract_figure_transformer.display_data_priority = ['latex', 'svg', 'png', 'jpg', 'jpeg' , 'text']
         self.extract_figure_transformer.extra_ext_map={'svg':'pdf'}
-        
-        
-    def _init_environment(self):
-        self.environment = Environment(
-            loader=FileSystemLoader([
-                os.path.dirname(os.path.realpath(__file__)) + LATEX_TEMPLATE_PATH,
-                os.path.dirname(os.path.realpath(__file__)) + LATEX_TEMPLATE_SKELETON_PATH,
-                ]),
-            extensions=exporter.JINJA_EXTENSIONS
-            )
 
-        #Set special Jinja2 syntax that will not conflict with latex.
-        self.environment.block_start_string = LATEX_JINJA_LOGIC_BLOCK[0]
-        self.environment.block_end_string = LATEX_JINJA_LOGIC_BLOCK[1]
-        self.environment.variable_start_string = LATEX_JINJA_VARIABLE_BLOCK[0]
-        self.environment.variable_end_string = LATEX_JINJA_VARIABLE_BLOCK[1]
-        self.environment.comment_start_string = LATEX_JINJA_COMMENT_BLOCK[0]
-        self.environment.comment_end_string = LATEX_JINJA_COMMENT_BLOCK[1]
-        
         
     def _register_filters(self):
+        """
+        Register all of the filters required for the exporter.
+        """
         
         #Register the filters of the base class.
         super(LatexExporter, self)._register_filters()
 
         #Add latex filters to the Jinja2 environment
         self.register_filter('escape_tex', nbconvert.filters.latex.escape_latex) 
         self.register_filter('highlight', nbconvert.filters.highlight.highlight2latex) 
     
     
     def _register_transformers(self):
+        """
+        Register all of the transformers needed for this exporter.
+        """
         
         #Register the transformers of the base class.
         super(LatexExporter, self)._register_transformers()
         
         #Register latex transformer
         self.register_transformer(LatexTransformer)
                     
  No newline at end of file

nbconvert/api/python.py

@@ -1,45 +1,62 b''
 """
 Python exporter which exports Notebook code into a PY file.
 """
 #-----------------------------------------------------------------------------
 # 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 Unicode
 
 # local import
 import exporter
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class PythonExporter(exporter.Exporter):
     """
     Exports a Python code file.
     """
     
     file_extension = Unicode(
         'py', config=True, 
         help="Extension of the file that should be written to disk")
 
     template_file = Unicode(
             'python', config=True,
             help="Name of the template file to use")
 
     def __init__(self, transformers=None, filters=None, config=None, armor=False, **kw):
+        """
+        Public constructor
+    
+        Parameters
+        ----------
+        transformers : list[of transformer]
+            Custom transformers to apply to the notebook prior to engaging
+            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.
+        config : config
+            User configuration instance.
+        """
         
         #Call base class constructor.
         super(PythonExporter, self).__init__(transformers, filters, config, **kw)
 
         #Set defaults
         self.extract_figure_transformer.enabled = False
         

nbconvert/api/reveal.py

@@ -1,47 +1,50 b''
 """
 Reveal slide show exporter.
 """
 #-----------------------------------------------------------------------------
 # 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 Unicode
 
 # local import
 import basichtml
 
 import nbconvert.transformers.revealhelp
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class RevealExporter(basichtml.BasicHtmlExporter):
     """
     Exports a Reveal slide show (.HTML) which may be rendered in a web browser.
     """
     
     file_extension = Unicode(
         'reveal.html', config=True, 
         help="Extension of the file that should be written to disk")
 
     template_file = Unicode(
             'reveal', config=True,
             help="Name of the template file to use")
     
     def _register_transformers(self):
+        """
+        Register all of the transformers needed for this exporter.
+        """
         
         #Register the transformers of the base class.
         super(RevealExporter, self)._register_transformers()
         
         #Register reveal help transformer
         self.register_transformer(nbconvert.transformers.revealhelp.RevealHelpTransformer)
         
  No newline at end of file