flavor=template

IPython/nbconvert/exporters/exporter.py

@@ -1,471 +1,480 b''
 """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
 import copy
 import collections
 import datetime
 
 # other libs/dependencies
 from jinja2 import Environment, FileSystemLoader, ChoiceLoader
 
 # IPython imports
 from IPython.config.configurable import Configurable
 from IPython.config import Config
 from IPython.nbformat import current as nbformat
 from IPython.utils.traitlets import MetaHasTraits, DottedObjectName, Unicode, List, Dict
 from IPython.utils.importstring import import_item
 from IPython.utils.text import indent
 from IPython.utils import py3compat
 
 from IPython.nbconvert import transformers as nbtransformers
 from IPython.nbconvert import filters
 
 #-----------------------------------------------------------------------------
 # Globals and constants
 #-----------------------------------------------------------------------------
 
 #Jinja2 extensions to load.
 JINJA_EXTENSIONS = ['jinja2.ext.loopcontrols']
 
 default_filters = {
         'indent': indent,
         'markdown2html': filters.markdown2html,
         'ansi2html': filters.ansi2html,
         'filter_data_type': filters.DataTypeFilter,
         'get_lines': filters.get_lines,
         'highlight2html': filters.highlight2html,
         'highlight2latex': filters.highlight2latex,
         'ipython2python': filters.ipython2python,
         'markdown2latex': filters.markdown2latex,
         'markdown2rst': filters.markdown2rst,
         'comment_lines': filters.comment_lines,
         'strip_ansi': filters.strip_ansi,
         'strip_dollars': filters.strip_dollars,
         'strip_files_prefix': filters.strip_files_prefix,
         'html2text' : filters.html2text,
         'add_anchor': filters.add_anchor,
         'ansi2latex': filters.ansi2latex,
         'strip_math_space': filters.strip_math_space,
         'wrap_text': filters.wrap_text,
         'escape_latex': filters.escape_latex
 }
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class ResourcesDict(collections.defaultdict):
     def __missing__(self, key):
         return ''
 
 
 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.
     """
     
     # finish the docstring
     __doc__ = __doc__.format(filters = '- '+'\n    - '.join(default_filters.keys()))
 
 
-    flavor = Unicode(config=True, help="""Flavor of the data format to use.  
-        I.E. 'full' or 'basic'""")
-
-    template_file = Unicode(
+    template_file = Unicode(u'default',
             config=True,
             help="Name of the template file to use")
+    def _template_file_changed(self, name, old, new):
+        if new=='default':
+            self.template_file = self.default_template
+        else:
+            self.template_file = new
+    default_template = Unicode(u'')
 
     file_extension = Unicode(
         'txt', config=True, 
         help="Extension of the file that should be written to disk"
         )
 
     template_path = List(['.'], config=True)
 
     default_template_path = Unicode(
         os.path.join("..", "templates"), 
         help="Path where the template files are located.")
 
     template_skeleton_path = Unicode(
         os.path.join("..", "templates", "skeleton"), 
         help="Path where the template skeleton files are located.") 
 
     #Jinja block definitions
     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(".tpl", config=True)
 
     #Configurability, allows the user to easily add filters and transformers.
     transformers = List(config=True,
         help="""List of transformers, by name or namespace, to enable.""")
 
     filters = Dict(config=True,
         help="""Dictionary of filters, by name and namespace, to add to the Jinja
         environment.""")
 
     default_transformers = List([nbtransformers.coalesce_streams,
                                  nbtransformers.SVG2PDFTransformer,
                                  nbtransformers.ExtractOutputTransformer,
                                  nbtransformers.CSSHTMLHeaderTransformer,
                                  nbtransformers.RevealHelpTransformer,
                                  nbtransformers.LatexTransformer,
                                  nbtransformers.SphinxTransformer],
         config=True,
         help="""List of transformers available by default, by name, namespace, 
         instance, or type.""")
 
 
     def __init__(self, config=None, extra_loaders=None, **kw):
         """
         Public constructor
     
         Parameters
         ----------
         config : config
             User configuration instance.
         extra_loaders : list[of Jinja Loaders]
             ordered list of Jinja loder to find templates. Will be tried in order
             before the default FileSysteme ones.
-        flavor : str
-            Flavor to use when exporting.  This determines what template to use
-            if one hasn't been specifically provided.
+        template : str (optional, kw arg)
+            Template to use when exporting.
         """
         
         #Call the base class constructor
         c = self.default_config
         if config:
             c.merge(config)
 
         super(Exporter, self).__init__(config=c, **kw)
 
         #Init
         self._init_template(**kw)
         self._init_environment(extra_loaders=extra_loaders)
         self._init_transformers()
         self._init_filters()
 
 
     @property
     def default_config(self):
         return Config()
 
     
     def from_notebook_node(self, nb, resources=None, **kw):
         """
         Convert a notebook from a notebook node instance.
     
         Parameters
         ----------
         nb : Notebook node
         resources : dict (**kw) 
             of additional resources that can be accessed read/write by 
             transformers and filters.
         """
         nb_copy = copy.deepcopy(nb)
         resources = self._init_resources(resources)
 
-        #Preprocess
+        # Preprocess
         nb_copy, resources = self._transform(nb_copy, resources)
 
-        #Convert
-        self.template = self.environment.get_template(self.template_file + self.template_extension)
-        output = self.template.render(nb=nb_copy, resources=resources)
+        # Try different template names during conversion.  First try to load the
+        # template by name with extension added, then try loading the template
+        # as if the name is explicitly specified, then try the name as a 
+        # 'flavor', and lastly just try to load the template by module name.
+        module_name = self.__module__.split('.')[-1]
+        try_names = [self.template_file + self.template_extension,
+                     self.template_file,
+                     module_name + '_' + self.template_file + self.template_extension,
+                     module_name + self.template_extension]
+        for try_name in try_names:
+            try:
+                self.template = self.environment.get_template(try_name)
+                break
+            except:
+                pass
+
+        if hasattr(self, 'template'):
+            output = self.template.render(nb=nb_copy, resources=resources)
+        else:
+            raise IOError('template file "%s" could not be found' % self.template_file)
         return output, resources
 
 
     def from_filename(self, filename, resources=None, **kw):
         """
         Convert a notebook from a notebook file.
     
         Parameters
         ----------
         filename : str
             Full filename of the notebook file to open and convert.
         """
 
         #Pull the metadata from the filesystem.
         if resources is None:
             resources = ResourcesDict()
         if not 'metadata' in resources or resources['metadata'] == '':
             resources['metadata'] = ResourcesDict()
         basename = os.path.basename(filename)
         notebook_name = basename[:basename.rfind('.')]
         resources['metadata']['name'] = notebook_name
 
         modified_date = datetime.datetime.fromtimestamp(os.path.getmtime(filename))
         resources['metadata']['modified_date'] = modified_date.strftime("%B %-d, %Y")
         
         with io.open(filename) as f:
             return self.from_notebook_node(nbformat.read(f, 'json'), resources=resources,**kw)
 
 
     def from_file(self, file_stream, resources=None, **kw):
         """
         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'), resources=resources, **kw)
 
 
     def register_transformer(self, transformer, enabled=False):
         """
         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 transformer is None:
             raise TypeError('transformer')
         isclass = isinstance(transformer, type)
         constructed = not isclass
 
         #Handle transformer's registration based on it's type
         if constructed and isinstance(transformer, py3compat.string_types):
             #Transformer is a string, import the namespace and recursively call
             #this register_transformer method
             transformer_cls = import_item(transformer)
             return self.register_transformer(transformer_cls, enabled)
         
         if constructed and hasattr(transformer, '__call__'):
             #Transformer is a function, no need to construct it.
             #Register and return the transformer.
             if enabled:
                 transformer.enabled = True
             self._transformers.append(transformer)
             return transformer
 
         elif isclass and isinstance(transformer, MetaHasTraits):
             #Transformer is configurable.  Make sure to pass in new default for 
             #the enabled flag if one was specified.
             self.register_transformer(transformer(parent=self), enabled)
 
         elif isclass:
             #Transformer is not configurable, construct it
             self.register_transformer(transformer(), enabled)
 
         else:
             #Transformer is an instance of something without a __call__ 
             #attribute.  
             raise TypeError('transformer')
 
 
     def register_filter(self, name, jinja_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 jinja_filter is None:
             raise TypeError('filter')
         isclass = isinstance(jinja_filter, type)
         constructed = not isclass
 
         #Handle filter's registration based on it's type
         if constructed and isinstance(jinja_filter, py3compat.string_types):
             #filter is a string, import the namespace and recursively call
             #this register_filter method
             filter_cls = import_item(jinja_filter)
             return self.register_filter(name, filter_cls)
         
         if constructed and hasattr(jinja_filter, '__call__'):
             #filter is a function, no need to construct it.
             self.environment.filters[name] = jinja_filter
             return jinja_filter
 
         elif isclass and isinstance(jinja_filter, MetaHasTraits):
             #filter is configurable.  Make sure to pass in new default for 
             #the enabled flag if one was specified.
             filter_instance = jinja_filter(parent=self)
             self.register_filter(name, filter_instance )
 
         elif isclass:
             #filter is not configurable, construct it
             filter_instance = jinja_filter()
             self.register_filter(name, filter_instance)
 
         else:
             #filter is an instance of something without a __call__ 
             #attribute.  
             raise TypeError('filter')
 
         
     def _init_template(self, **kw):
         """
         Make sure a template name is specified.  If one isn't specified, try to
         build one from the information we know.
         """
-
-        # Set the template_file if it has not been set explicitly.
-        if not self.template_file:
-
-            # Build the template file name from the name of the exporter and the
-            # flavor (if available).  The flavor can be set on the traitlet
-            # or passed in as a kw arg.  The flavor specified in kw overrides
-            # what is set in the flavor traitlet.
-            module_name = self.__module__.split('.')[-1]
-            if self.flavor or 'flavor' in kw:
-                self.template_file = module_name + '_' + kw.get('flavor', self.flavor)
-            else:
-                self.template_file = module_name
+        self._template_file_changed('template_file', self.template_file, self.template_file)
+        if 'template' in kw:
+            self.template_file = kw['template']
         
 
     def _init_environment(self, extra_loaders=None):
         """
         Create the Jinja templating environment.
         """
         here = os.path.dirname(os.path.realpath(__file__))
         loaders = []
         if extra_loaders:
             loaders.extend(extra_loaders)
 
         paths = self.template_path
         paths.extend([os.path.join(here, self.default_template_path),
                       os.path.join(here, self.template_skeleton_path)])
         loaders.append(FileSystemLoader(paths))
 
         self.environment = Environment(
             loader= ChoiceLoader(loaders),
             extensions=JINJA_EXTENSIONS
             )
         
         #Set special Jinja2 syntax that will not conflict with latex.
         if self.jinja_logic_block_start:
             self.environment.block_start_string = self.jinja_logic_block_start
         if self.jinja_logic_block_end:
             self.environment.block_end_string = self.jinja_logic_block_end
         if self.jinja_variable_block_start:
             self.environment.variable_start_string = self.jinja_variable_block_start
         if self.jinja_variable_block_end:
             self.environment.variable_end_string = self.jinja_variable_block_end
         if self.jinja_comment_block_start:
             self.environment.comment_start_string = self.jinja_comment_block_start
         if self.jinja_comment_block_end:
             self.environment.comment_end_string = self.jinja_comment_block_end
 
     
     def _init_transformers(self):
         """
         Register all of the transformers needed for this exporter, disabled
         unless specified explicitly.
         """
         self._transformers = []
 
         #Load default transformers (not necessarly enabled by default).
         if self.default_transformers:
             for transformer in self.default_transformers:
                 self.register_transformer(transformer)
 
         #Load user transformers.  Enable by default.
         if self.transformers:
             for transformer in self.transformers:
                 self.register_transformer(transformer, enabled=True)
  
 
     def _init_filters(self):
         """
         Register all of the filters required for the exporter.
         """
         
         #Add default filters to the Jinja2 environment
         for key, value in default_filters.items():
             self.register_filter(key, value)
 
         #Load user filters.  Overwrite existing filters if need be.
         if self.filters:
             for key, user_filter in self.filters.items():
                 self.register_filter(key, user_filter)
 
 
     def _init_resources(self, resources):
 
         #Make sure the resources dict is of ResourcesDict type.
         if resources is None:
             resources = ResourcesDict()
         if not isinstance(resources, ResourcesDict):
             new_resources = ResourcesDict()
             new_resources.update(resources)
             resources = new_resources 
 
         #Make sure the metadata extension exists in resources
         if 'metadata' in resources:
             if not isinstance(resources['metadata'], ResourcesDict):
                 resources['metadata'] = ResourcesDict(resources['metadata'])
         else:
             resources['metadata'] = ResourcesDict()
             if not resources['metadata']['name']: 
                 resources['metadata']['name'] = 'Notebook'
 
         #Set the output extension
         resources['output_extension'] = self.file_extension
         return resources
         
 
     def _transform(self, nb, resources):
         """
         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.
         resources : a dict of additional resources that
             can be accessed read/write by transformers
             and filters.
         """
         
         # Do a copy.deepcopy first, 
         # we are never safe enough with what the transformers could do.
         nbc =  copy.deepcopy(nb)
         resc = copy.deepcopy(resources)
 
         #Run each transformer on the notebook.  Carry the output along
         #to each transformer
         for transformer in self._transformers:
             nbc, resc = transformer(nbc, resc)
         return nbc, resc

IPython/nbconvert/exporters/html.py

@@ -1,55 +1,52 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, List
 
 from IPython.nbconvert import transformers
 from IPython.config import Config
 
 from .exporter import Exporter
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class HTMLExporter(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 transformers/filters.  If you don't need custom transformers/
     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"
         )
 
-    flavor = Unicode('full', config=True, help="""Flavor of the data format to 
-        use.  I.E. 'full' or 'basic'""")
+    default_template = Unicode('full', config=True, help="""Flavor of the data 
+        format to use.  I.E. 'full' or 'basic'""")
 
     @property
     def default_config(self):
         c = Config({
             'CSSHTMLHeaderTransformer':{
                 'enabled':True
-                },
-            'RevealHelpTransformer':{
-                'enabled':True,
-                },                
+                }          
             })
         c.merge(super(HTMLExporter,self).default_config)
         return c

IPython/nbconvert/exporters/latex.py

@@ -1,91 +1,91 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, List
 from IPython.config import Config
 
 from IPython.nbconvert import filters, transformers
 from .exporter import Exporter
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class LatexExporter(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.
     """
     
     file_extension = Unicode(
         'tex', config=True, 
         help="Extension of the file that should be written to disk")
 
-    flavor = Unicode('article', config=True, help="""Flavor of the data format to 
-        use.  I.E. 'full' or 'basic'""")
+    default_template = Unicode('article', config=True, help="""Template of the 
+        data format to use.  I.E. 'full' or 'basic'""")
 
     #Latex constants
     default_template_path = Unicode(
         os.path.join("..", "templates", "latex"), config=True,
         help="Path where the template files are located.")
 
     template_skeleton_path = Unicode(
         os.path.join("..", "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)
 
 
     @property
     def default_config(self):
         c = Config({
             'NbConvertBase': {
                 'display_data_priority' : ['latex', 'pdf', 'png', 'jpg', 'svg', 'jpeg', 'text']
                 },
              'ExtractOutputTransformer': {
                     'enabled':True
                  },
              'SVG2PDFTransformer': {
                     'enabled':True
                  },
              'LatexTransformer': {
                     'enabled':True
                  },
              'SphinxTransformer': {
                     'enabled':True
                  }
          })
         c.merge(super(LatexExporter,self).default_config)
         return c

IPython/nbconvert/exporters/slides.py

@@ -1,52 +1,52 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
 
 from IPython.nbconvert import transformers
 from IPython.config import Config
 
 from .exporter import Exporter
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class SlidesExporter(Exporter):
     """
     Exports slides
     """
     
     file_extension = Unicode(
         'html', config=True, 
         help="Extension of the file that should be written to disk"
         )
 
-    flavor = Unicode('reveal', config=True, help="""Flavor of the data format to 
-        use.  I.E. 'reveal'""")
+    default_template = Unicode('reveal', config=True, help="""Template of the 
+        data format to use.  I.E. 'reveal'""")
 
     @property
     def default_config(self):
         c = Config({
             'CSSHTMLHeaderTransformer':{
                 'enabled':True
                 },
             'RevealHelpTransformer':{
                 'enabled':True,
                 },                
             })
         c.merge(super(SlidesExporter,self).default_config)
         return c

IPython/nbconvert/exporters/tests/test_html.py

@@ -1,56 +1,56 b''
 """
 Module with tests for html.py
 """
 
 #-----------------------------------------------------------------------------
 # 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 ExportersTestsBase
 from ..html import HTMLExporter
 from IPython.testing.decorators import onlyif_cmds_exist
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class TestHTMLExporter(ExportersTestsBase):
     """Contains test functions for html.py"""
 
     def test_constructor(self):
         """
         Can a HTMLExporter be constructed?
         """
         HTMLExporter()
 
     @onlyif_cmds_exist('pandoc')
     def test_export(self):
         """
         Can a HTMLExporter export something?
         """
         (output, resources) = HTMLExporter().from_filename(self._get_notebook())
         assert len(output) > 0
 
 
     def test_export_basic(self):
         """
-        Can a HTMLExporter export using the 'basic' flavor?
+        Can a HTMLExporter export using the 'basic' template?
         """
-        (output, resources) = HTMLExporter(flavor='basic').from_filename(self._get_notebook())
+        (output, resources) = HTMLExporter(template='basic').from_filename(self._get_notebook())
         assert len(output) > 0
 
 
     def test_export_full(self):
         """
-        Can a HTMLExporter export using the 'full' flavor?
+        Can a HTMLExporter export using the 'full' template?
         """
-        (output, resources) = HTMLExporter(flavor='full').from_filename(self._get_notebook())
+        (output, resources) = HTMLExporter(template='full').from_filename(self._get_notebook())
         assert len(output) > 0

IPython/nbconvert/exporters/tests/test_latex.py

@@ -1,65 +1,65 b''
 """
 Module with tests for latex.py
 """
 
 #-----------------------------------------------------------------------------
 # 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 ExportersTestsBase
 from ..latex import LatexExporter
 from IPython.testing.decorators import onlyif_cmds_exist
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class TestLatexExporter(ExportersTestsBase):
     """Contains test functions for latex.py"""
 
     def test_constructor(self):
         """
         Can a LatexExporter be constructed?
         """
         LatexExporter()
 
 
     @onlyif_cmds_exist('pandoc')
     def test_export(self):
         """
         Can a LatexExporter export something?
         """
         (output, resources) = LatexExporter().from_filename(self._get_notebook())
         assert len(output) > 0
 
 
     def test_export_book(self):
         """
-        Can a LatexExporter export using 'book' flavor?
+        Can a LatexExporter export using 'book' template?
         """
-        (output, resources) = LatexExporter(flavor='book').from_filename(self._get_notebook())
+        (output, resources) = LatexExporter(template='book').from_filename(self._get_notebook())
         assert len(output) > 0
 
 
     def test_export_basic(self):
         """
-        Can a LatexExporter export using 'basic' flavor?
+        Can a LatexExporter export using 'basic' template?
         """
-        (output, resources) = LatexExporter(flavor='basic').from_filename(self._get_notebook())
+        (output, resources) = LatexExporter(template='basic').from_filename(self._get_notebook())
         assert len(output) > 0
 
 
     def test_export_article(self):
         """
-        Can a LatexExporter export using 'article' flavor?
+        Can a LatexExporter export using 'article' template?
         """
-        (output, resources) = LatexExporter(flavor='article').from_filename(self._get_notebook())
+        (output, resources) = LatexExporter(template='article').from_filename(self._get_notebook())
         assert len(output) > 0
  No newline at end of file

IPython/nbconvert/exporters/tests/test_slides.py

@@ -1,47 +1,47 b''
 """
 Module with tests for slides.py
 """
 
 #-----------------------------------------------------------------------------
 # 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 ExportersTestsBase
 from ..slides import SlidesExporter
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class TestSlidesExporter(ExportersTestsBase):
     """Contains test functions for slides.py"""
 
     def test_constructor(self):
         """
         Can a SlidesExporter be constructed?
         """
         SlidesExporter()
 
 
     def test_export(self):
         """
         Can a SlidesExporter export something?
         """
         (output, resources) = SlidesExporter().from_filename(self._get_notebook())
         assert len(output) > 0
 
 
     def test_export_reveal(self):
         """
-        Can a SlidesExporter export using the 'reveal' flavor?
+        Can a SlidesExporter export using the 'reveal' template?
         """
-        (output, resources) = SlidesExporter(flavor='reveal').from_filename(self._get_notebook())
+        (output, resources) = SlidesExporter(template='reveal').from_filename(self._get_notebook())
         assert len(output) > 0

IPython/nbconvert/nbconvertapp.py

@@ -1,259 +1,258 b''
 #!/usr/bin/env python
 """NBConvert is a utility for conversion of .ipynb files.
 
 Command-line interface for the NbConvert conversion utility.
 """
 #-----------------------------------------------------------------------------
 #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
 from __future__ import print_function
 import sys
 import os
 import glob
 
 # From IPython
 from IPython.core.application import BaseIPythonApplication, base_aliases, base_flags
 from IPython.config import catch_config_error, Configurable
 from IPython.utils.traitlets import (
     Unicode, List, Instance, DottedObjectName, Type, CaselessStrEnum,
 )
 from IPython.utils.importstring import import_item
 
 from .exporters.export import export_by_name, get_export_names, ExporterNameError
 from IPython.nbconvert import exporters, transformers, writers
 from .utils.base import NbConvertBase
 from .utils.exceptions import ConversionException
 
 #-----------------------------------------------------------------------------
 #Classes and functions
 #-----------------------------------------------------------------------------
 
 nbconvert_aliases = {}
 nbconvert_aliases.update(base_aliases)
 nbconvert_aliases.update({
     'to' : 'NbConvertApp.export_format',
-    'flavor' : 'Exporter.flavor',
     'template' : 'Exporter.template_file',
     'notebooks' : 'NbConvertApp.notebooks',
     'writer' : 'NbConvertApp.writer_class',
 })
 
 nbconvert_flags = {}
 nbconvert_flags.update(base_flags)
 nbconvert_flags.update({
     'stdout' : (
         {'NbConvertApp' : {'writer_class' : "StdoutWriter"}},
         "Write notebook output to stdout instead of files."
         ),
 
     'pdf' : (
         {'NbConvertApp' : {'writer_class' : "PDFWriter"}},
-        "Compile notebook output to a PDF."
+        "Compile notebook output to a PDF (requires `--to latex`)."
         )
 })
 
 
 class NbConvertApp(BaseIPythonApplication):
     """Application used to convert to and from notebook file type (*.ipynb)"""
 
     name = 'ipython-nbconvert'
     aliases = nbconvert_aliases
     flags = nbconvert_flags
     
     def _classes_default(self):
         classes = [NbConvertBase]
         for pkg in (exporters, transformers, writers):
             for name in dir(pkg):
                 cls = getattr(pkg, name)
                 if isinstance(cls, type) and issubclass(cls, Configurable):
                     classes.append(cls)
         return classes
 
     description = Unicode(
         u"""This application is used to convert notebook files (*.ipynb)
         to various other formats.""")
 
     examples = Unicode(u"""
         The simplest way to use nbconvert is
         
         > ipython nbconvert mynotebook.ipynb
         
         which will convert mynotebook.ipynb to the default format (probably HTML).
         
         You can specify the export format with `--to`.
         Options include {0}
         
         > ipython nbconvert --to latex mynotebook.ipnynb
 
-        Both HTML and LaTeX support multiple flavors of output. LaTeX includes
+        Both HTML and LaTeX support multiple output templates. LaTeX includes
         'basic', 'book', and 'article'.  HTML includes 'basic' and 'full'.  You 
         can specify the flavor of the format used.
 
-        > ipython nbconvert --to html --flavor reveal mynotebook.ipnynb
+        > ipython nbconvert --to html --template reveal mynotebook.ipnynb
         
         You can also pipe the output to stdout, rather than a file
         
         > ipython nbconvert mynotebook.ipynb --stdout
 
         or to a PDF
 
-        > ipython nbconvert mynotebook.ipynb --pdf
+        > ipython nbconvert mynotebook.ipynb --to latex --pdf
         
         Multiple notebooks can be given at the command line in a couple of 
         different ways:
   
         > ipython nbconvert notebook*.ipynb
         > ipython nbconvert notebook1.ipynb notebook2.ipynb
         
         or you can specify the notebooks list in a config file, containing::
         
             c.NbConvertApp.notebooks = ["my_notebook.ipynb"]
         
         > ipython nbconvert --config mycfg.py
         """.format(get_export_names()))
     # Writer specific variables
     writer = Instance('IPython.nbconvert.writers.base.WriterBase',  
                       help="""Instance of the writer class used to write the 
                       results of the conversion.""")
     writer_class = DottedObjectName('FilesWriter', config=True, 
                                     help="""Writer class used to write the 
                                     results of the conversion""")
     writer_aliases = {'FilesWriter': 'IPython.nbconvert.writers.files.FilesWriter',
                       'PDFWriter': 'IPython.nbconvert.writers.pdf.PDFWriter',
                       'DebugWriter': 'IPython.nbconvert.writers.debug.DebugWriter',
                       'StdoutWriter': 'IPython.nbconvert.writers.stdout.StdoutWriter'}
     writer_factory = Type()
 
     def _writer_class_changed(self, name, old, new):
         if new in self.writer_aliases:
             new = self.writer_aliases[new]
         self.writer_factory = import_item(new)
 
 
     # Other configurable variables
     export_format = CaselessStrEnum(get_export_names(),
         default_value="html",
         config=True,
         help="""The export format to be used."""
     )
 
     notebooks = List([], config=True, help="""List of notebooks to convert.
                      Wildcards are supported.
                      Filenames passed positionally will be added to the list.
                      """)
 
     @catch_config_error
     def initialize(self, argv=None):
         super(NbConvertApp, self).initialize(argv)
         self.init_syspath()
         self.init_notebooks()
         self.init_writer()
 
 
     def init_syspath(self):
         """
         Add the cwd to the sys.path ($PYTHONPATH)
         """
         sys.path.insert(0, os.getcwd())
         
 
     def init_notebooks(self):
         """Construct the list of notebooks.
         If notebooks are passed on the command-line,
         they override notebooks specified in config files.
         Glob each notebook to replace notebook patterns with filenames.
         """
 
         # Specifying notebooks on the command-line overrides (rather than adds)
         # the notebook list
         if self.extra_args:
             patterns = self.extra_args
         else:
             patterns = self.notebooks
 
         # Use glob to replace all the notebook patterns with filenames.
         filenames = []
         for pattern in patterns:
             
             # Use glob to find matching filenames.  Allow the user to convert 
             # notebooks without having to type the extension.
             globbed_files = glob.glob(pattern)
             globbed_files.extend(glob.glob(pattern + '.ipynb'))
 
             for filename in globbed_files:
                 if not filename in filenames:
                     filenames.append(filename)
         self.notebooks = filenames
 
     def init_writer(self):
         """
         Initialize the writer (which is stateless)
         """
         self._writer_class_changed(None, self.writer_class, self.writer_class)
         self.writer = self.writer_factory(parent=self)
 
     def start(self):
         """
         Ran after initialization completed
         """
         super(NbConvertApp, self).start()
         self.convert_notebooks()
 
     def convert_notebooks(self):
         """
         Convert the notebooks in the self.notebook traitlet
         """
         # Export each notebook
         conversion_success = 0
         for notebook_filename in self.notebooks:
 
             # Get a unique key for the notebook and set it in the resources object.
             basename = os.path.basename(notebook_filename)
             notebook_name = basename[:basename.rfind('.')]
             resources = {}
             resources['unique_key'] = notebook_name
             resources['output_files_dir'] = '%s_files' % notebook_name
 
             # Try to export
             try:
                 output, resources = export_by_name(self.export_format,
                                               notebook_filename, 
                                               resources=resources,
                                               config=self.config)
             except ExporterNameError as e:
                 print("Error while converting '%s': '%s' exporter not found."
                       %(notebook_filename, self.export_format),
                       file=sys.stderr)
                 print("Known exporters are:",
                       "\n\t" + "\n\t".join(get_export_names()),
                       file=sys.stderr)
                 self.exit(1)
             except ConversionException as e:
                 print("Error while converting '%s': %s" %(notebook_filename, e),
                       file=sys.stderr)
                 self.exit(1)
             else:
                 self.writer.write(output, resources, notebook_name=notebook_name)
                 conversion_success += 1
 
         # If nothing was converted successfully, help the user.
         if conversion_success == 0:
             self.print_help()
             sys.exit(-1)
 
 
 #-----------------------------------------------------------------------------
 # Main entry point
 #-----------------------------------------------------------------------------
 
 launch_new_instance = NbConvertApp.launch_instance

IPython/nbconvert/tests/test_nbconvertapp.py

@@ -1,135 +1,135 b''
 """
 Contains tests for the nbconvertapp
 """
 #-----------------------------------------------------------------------------
 #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
 from .base import TestsBase
 
 from IPython.utils import py3compat
 
     
 #-----------------------------------------------------------------------------
 # Constants
 #-----------------------------------------------------------------------------
 
 # Define ipython commandline name
 if py3compat.PY3:
     IPYTHON = 'ipython3'
 else:
     IPYTHON = 'ipython'
 
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class TestNbConvertApp(TestsBase):
     """Collection of NbConvertApp tests"""
 
 
     def test_notebook_help(self):
         """
         Will help show if no notebooks are specified?
         """
         with self.create_temp_cwd():
             assert "see '--help-all'" in self.call([IPYTHON, 'nbconvert'])
 
 
     def test_glob(self):
         """
         Do search patterns work for notebook names?
         """
         with self.create_temp_cwd(['notebook*.ipynb']):
             assert not 'error' in self.call([IPYTHON, 'nbconvert', 
                 '--to="python"', '--notebooks=["*.ipynb"]']).lower()
             assert os.path.isfile('notebook1.py')
             assert os.path.isfile('notebook2.py')
 
 
     def test_glob_subdir(self):
         """
         Do search patterns work for subdirectory notebook names?
         """
         with self.create_temp_cwd() as cwd:
             self.copy_files_to(['notebook*.ipynb'], 'subdir/')
             assert not 'error' in self.call([IPYTHON, 'nbconvert', '--to="python"', 
                 '--notebooks=["%s"]' % os.path.join('subdir', '*.ipynb')]).lower()
             assert os.path.isfile('notebook1.py')
             assert os.path.isfile('notebook2.py')
 
 
     def test_explicit(self):
         """
         Do explicit notebook names work?
         """
         with self.create_temp_cwd(['notebook*.ipynb']):
             assert not 'error' in self.call([IPYTHON, 'nbconvert', '--to="python"', 
                 '--notebooks=["notebook2.ipynb"]']).lower()
             assert not os.path.isfile('notebook1.py')
             assert os.path.isfile('notebook2.py')
 
 
-    def test_flavor(self):
+    def test_template(self):
         """
-        Do export flavors work?
+        Do export templates work?
         """
         with self.create_temp_cwd(['notebook*.ipynb']):
             assert not 'error' in self.call([IPYTHON, 'nbconvert', '--to="slides"', 
-                '--notebooks=["notebook2.ipynb"]', '--flavor="reveal"']).lower()
+                '--notebooks=["notebook2.ipynb"]', '--template="reveal"']).lower()
             assert os.path.isfile('notebook2.html')
             with open('notebook2.html') as f:
                 assert '/reveal.css' in f.read()
 
 
     def test_glob_explicit(self):
         """
         Can a search pattern be used along with matching explicit notebook names?
         """
         with self.create_temp_cwd(['notebook*.ipynb']):
             assert not 'error' in self.call([IPYTHON, 'nbconvert', '--to="python"', 
                 '--notebooks=["*.ipynb", "notebook1.ipynb", "notebook2.ipynb"]']).lower()
             assert os.path.isfile('notebook1.py')
             assert os.path.isfile('notebook2.py')
 
 
     def test_explicit_glob(self):
         """
         Can explicit notebook names be used and then a matching search pattern?
         """
         with self.create_temp_cwd(['notebook*.ipynb']):
             assert not 'error' in self.call([IPYTHON, 'nbconvert', '--to="python"', 
                 '--notebooks=["notebook1.ipynb", "notebook2.ipynb", "*.ipynb"]']).lower()
             assert os.path.isfile('notebook1.py')
             assert os.path.isfile('notebook2.py')
 
 
     def test_default_config(self):
         """
         Does the default config work?
         """
         with self.create_temp_cwd(['notebook*.ipynb', 'ipython_nbconvert_config.py']):
             assert not 'error' in self.call([IPYTHON, 'nbconvert']).lower()
             assert os.path.isfile('notebook1.py')
             assert not os.path.isfile('notebook2.py')
 
 
     def test_override_config(self):
         """
         Can the default config be overriden?
         """
         with self.create_temp_cwd(['notebook*.ipynb', 'ipython_nbconvert_config.py', 
                                    'override.py']):
             assert not 'error' in self.call([IPYTHON, 'nbconvert', '--config="override.py"']).lower()
             assert not os.path.isfile('notebook1.py')
             assert os.path.isfile('notebook2.py')

IPython/nbconvert/writers/pdf.py

@@ -1,42 +1,47 b''
 #!/usr/bin/env python
 """
 Contains writer for writing nbconvert output to PDF.
 """
 #-----------------------------------------------------------------------------
 #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 subprocess
 import os
 
-from IPython.utils.traitlets import Integer
+from IPython.utils.traitlets import Integer, Unicode
 
 from .files import FilesWriter
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class PDFWriter(FilesWriter):
     """Writer designed to write to PDF files"""
 
     iteration_count = Integer(3, config=True, help="""
         How many times pdflatex will be called.
         """)
 
+    compiler = Unicode(u'pdflatex {0}', config=True, help="""
+        Shell command used to compile PDF.""")
+
     def write(self, output, resources, notebook_name=None, **kw):
             """
             Consume and write Jinja output a PDF.  
             See files.py for more...
             """        
-            dest = super(PDFWriter, self).write(output, resources, notebook_name=notebook_name, **kw)
-            command = 'pdflatex ' + dest
+            dest = super(PDFWriter, self).write(output, resources, 
+                notebook_name=notebook_name, **kw)
+            command = self.compiler.format(dest)
+
             for index in range(self.iteration_count):
                 subprocess.Popen(command, shell=True, stdout=open(os.devnull, 'wb'))