Make nbconvert a little less chatty.

User don't really care what template is used by default.
and no need to say where the files might be written if they won't be.

IPython/nbconvert/exporters/templateexporter.py

@@ -1,321 +1,321 b''
 """This module defines TemplateExporter, 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 os
 
 # other libs/dependencies are imported at runtime
 # to move ImportErrors to runtime when the requirement is actually needed
 
 # IPython imports
 from IPython.utils.traitlets import MetaHasTraits, Unicode, List, Dict, Any
 from IPython.utils.importstring import import_item
 from IPython.utils import py3compat, text
 
 from IPython.nbconvert import filters
 from .exporter import Exporter
 
 #-----------------------------------------------------------------------------
 # Globals and constants
 #-----------------------------------------------------------------------------
 
 #Jinja2 extensions to load.
 JINJA_EXTENSIONS = ['jinja2.ext.loopcontrols']
 
 default_filters = {
         'indent': text.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,
         'posix_path': filters.posix_path,
         '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,
         'wrap_text': filters.wrap_text,
         'escape_latex': filters.escape_latex,
         'citation2latex': filters.citation2latex,
         'path2url': filters.path2url,
         'add_prompts': filters.add_prompts,
         'ascii_only': filters.ascii_only,
         'prevent_list_blocks': filters.prevent_list_blocks,
 }
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class TemplateExporter(Exporter):
     """
     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/preprocessors.  If the filters/
     preprocessors provided by default suffice, there is no need to inherit from
     this class.  Instead, override the template_file and file_extension
     traits via a config file.
 
     {filters}
     """
     
     # finish the docstring
     __doc__ = __doc__.format(filters = '- '+'\n    - '.join(default_filters.keys()))
 
 
     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
         self.template = None
         self._load_template()
     
     default_template = Unicode(u'')
     template = Any()
     environment = Any()
 
     template_path = List(['.'], config=True)
     def _template_path_changed(self, name, old, new):
         self._load_template()
 
     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)
 
     filters = Dict(config=True,
         help="""Dictionary of filters, by name and namespace, to add to the Jinja
         environment.""")
 
     raw_mimetypes = List(config=True,
         help="""formats of raw cells to be included in this Exporter's output."""
     )
     def _raw_mimetypes_default(self):
         return [self.output_mimetype, '']
 
 
     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 loader to find templates. Will be tried in order
             before the default FileSystem ones.
         template : str (optional, kw arg)
             Template to use when exporting.
         """
         super(TemplateExporter, self).__init__(config=config, **kw)
 
         #Init
         self._init_template()
         self._init_environment(extra_loaders=extra_loaders)
         self._init_filters()
 
 
     def _load_template(self):
         """Load the Jinja template object from the template file
         
         This is a no-op if the template attribute is already defined,
         or the Jinja environment is not setup yet.
         
         This is triggered by various trait changes that would change the template.
         """
         from jinja2 import TemplateNotFound
         
         if self.template is not None:
             return
         # called too early, do nothing
         if self.environment is None:
             return
         # 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.
         try_names = []
         if self.template_file:
             try_names.extend([
                 self.template_file + self.template_extension,
                 self.template_file,
             ])
         for try_name in try_names:
             self.log.debug("Attempting to load template %s", try_name)
             try:
                 self.template = self.environment.get_template(try_name)
             except (TemplateNotFound, IOError):
                 pass
             except Exception as e:
                 self.log.warn("Unexpected exception loading template: %s", try_name, exc_info=True)
             else:
-                self.log.info("Loaded template %s", try_name)
+                self.log.debug("Loaded template %s", try_name)
                 break
 
     def from_notebook_node(self, nb, resources=None, **kw):
         """
         Convert a notebook from a notebook node instance.
     
         Parameters
         ----------
         nb : :class:`~IPython.nbformat.NotebookNode`
           Notebook node
         resources : dict
           Additional resources that can be accessed read/write by
           preprocessors and filters.
         """
         nb_copy, resources = super(TemplateExporter, self).from_notebook_node(nb, resources, **kw)
         resources.setdefault('raw_mimetypes', self.raw_mimetypes)
 
         self._load_template()
 
         if self.template is not None:
             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 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):
         """
         Make sure a template name is specified.  If one isn't specified, try to
         build one from the information we know.
         """
         self._template_file_changed('template_file', self.template_file, self.template_file)
         
 
     def _init_environment(self, extra_loaders=None):
         """
         Create the Jinja templating environment.
         """
         from jinja2 import Environment, ChoiceLoader, FileSystemLoader
         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_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)

IPython/nbconvert/nbconvertapp.py

@@ -1,341 +1,340 b''
 #!/usr/bin/env python
 """NbConvert is a utility for conversion of .ipynb files.
 
 Command-line interface for the NbConvert conversion utility.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 
 import logging
 import sys
 import os
 import glob
 
 from IPython.core.application import BaseIPythonApplication, base_aliases, base_flags
 from IPython.core.profiledir import ProfileDir
 from IPython.config import catch_config_error, Configurable
 from IPython.utils.traitlets import (
     Unicode, List, Instance, DottedObjectName, Type, CaselessStrEnum, Bool,
 )
 from IPython.utils.importstring import import_item
 
 from .exporters.export import get_export_names, exporter_map
 from IPython.nbconvert import exporters, preprocessors, writers, postprocessors
 from .utils.base import NbConvertBase
 from .utils.exceptions import ConversionException
 
 #-----------------------------------------------------------------------------
 #Classes and functions
 #-----------------------------------------------------------------------------
 
 class DottedOrNone(DottedObjectName):
     """
     A string holding a valid dotted object name in Python, such as A.b3._c
     Also allows for None type."""
     
     default_value = u''
 
     def validate(self, obj, value):
         if value is not None and len(value) > 0:
             return super(DottedOrNone, self).validate(obj, value)
         else:
             return value
             
 nbconvert_aliases = {}
 nbconvert_aliases.update(base_aliases)
 nbconvert_aliases.update({
     'to' : 'NbConvertApp.export_format',
     'template' : 'TemplateExporter.template_file',
     'writer' : 'NbConvertApp.writer_class',
     'post': 'NbConvertApp.postprocessor_class',
     'output': 'NbConvertApp.output_base',
     'reveal-prefix': 'RevealHelpPreprocessor.url_prefix',
     'nbformat': 'NotebookExporter.nbformat_version',
 })
 
 nbconvert_flags = {}
 nbconvert_flags.update(base_flags)
 nbconvert_flags.update({
     'execute' : (
         {'ExecutePreprocessor' : {'enabled' : True}},
         "Execute the notebook prior to export."
         ),
     'stdout' : (
         {'NbConvertApp' : {'writer_class' : "StdoutWriter"}},
         "Write notebook output to stdout instead of files."
         ),
     'inplace' : (
         {
             'NbConvertApp' : {'use_output_suffix' : False},
             'FilesWriter': {'build_directory': ''}
         },
         """Run nbconvert in place, overwriting the existing notebook (only 
         relevant when converting to notebook format)"""
         )
 })
 
 
 class NbConvertApp(BaseIPythonApplication):
     """Application used to convert from notebook file type (``*.ipynb``)"""
 
     name = 'ipython-nbconvert'
     aliases = nbconvert_aliases
     flags = nbconvert_flags
     
     def _log_level_default(self):
         return logging.INFO
     
     def _classes_default(self):
         classes = [NbConvertBase, ProfileDir]
         for pkg in (exporters, preprocessors, writers, postprocessors):
             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.
 
         WARNING: THE COMMANDLINE INTERFACE MAY CHANGE IN FUTURE RELEASES.""")
 
     output_base = Unicode('', config=True, help='''overwrite base name use for output files.
             can only be used when converting one notebook at a time.
             ''')
 
     use_output_suffix = Bool(
         True, 
         config=True,
         help="""Whether to apply a suffix prior to the extension (only relevant
             when converting to notebook format). The suffix is determined by
             the exporter, and is usually '.nbconvert'.""")
 
     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.ipynb
 
         Both HTML and LaTeX support multiple output templates. LaTeX includes
         'base', 'article' and 'report'.  HTML includes 'basic' and 'full'. You
         can specify the flavor of the format used.
 
         > ipython nbconvert --to html --template basic mynotebook.ipynb
         
         You can also pipe the output to stdout, rather than a file
         
         > ipython nbconvert mynotebook.ipynb --stdout
 
         PDF is generated via latex
 
         > ipython nbconvert mynotebook.ipynb --to pdf
         
         You can get (and serve) a Reveal.js-powered slideshow
         
         > ipython nbconvert myslides.ipynb --to slides --post serve
         
         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',
                       '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.lower() in self.writer_aliases:
             new = self.writer_aliases[new.lower()]
         self.writer_factory = import_item(new)
 
     # Post-processor specific variables
     postprocessor = Instance('IPython.nbconvert.postprocessors.base.PostProcessorBase',  
                       help="""Instance of the PostProcessor class used to write the 
                       results of the conversion.""")
 
     postprocessor_class = DottedOrNone(config=True, 
                                     help="""PostProcessor class used to write the 
                                     results of the conversion""")
     postprocessor_aliases = {'serve': 'IPython.nbconvert.postprocessors.serve.ServePostProcessor'}
     postprocessor_factory = Type()
 
     def _postprocessor_class_changed(self, name, old, new):
         if new.lower() in self.postprocessor_aliases:
             new = self.postprocessor_aliases[new.lower()]
         if new:
             self.postprocessor_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):
         self.init_syspath()
         super(NbConvertApp, self).initialize(argv)
         self.init_notebooks()
         self.init_writer()
         self.init_postprocessor()
 
 
 
     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'))
             if not globbed_files:
                 self.log.warn("pattern %r matched no files", pattern)
 
             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)
         if hasattr(self.writer, 'build_directory') and self.writer.build_directory != '':
             self.use_output_suffix = False
 
     def init_postprocessor(self):
         """
         Initialize the postprocessor (which is stateless)
         """
         self._postprocessor_class_changed(None, self.postprocessor_class, 
             self.postprocessor_class)
         if self.postprocessor_factory:
             self.postprocessor = self.postprocessor_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
 
         if self.output_base != '' and len(self.notebooks) > 1:
             self.log.error(
             """UsageError: --output flag or `NbConvertApp.output_base` config option
             cannot be used when converting multiple notebooks.
             """)
             self.exit(1)
         
         exporter = exporter_map[self.export_format](config=self.config)
 
         for notebook_filename in self.notebooks:
             self.log.info("Converting notebook %s to %s", notebook_filename, self.export_format)
 
             # 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('.')]
             if self.output_base:
                 # strip duplicate extension from output_base, to avoid Basname.ext.ext
                 if getattr(exporter, 'file_extension', False):
                     base, ext = os.path.splitext(self.output_base)
                     if ext == exporter.file_extension:
                         self.output_base = base
                 notebook_name = self.output_base
             resources = {}
             resources['profile_dir'] = self.profile_dir.location
             resources['unique_key'] = notebook_name
             resources['output_files_dir'] = '%s_files' % notebook_name
-            self.log.info("Support files will be in %s", os.path.join(resources['output_files_dir'], ''))
 
             # Try to export
             try:
                 output, resources = exporter.from_filename(notebook_filename, resources=resources)
             except ConversionException as e:
                 self.log.error("Error while converting '%s'", notebook_filename,
                       exc_info=True)
                 self.exit(1)
             else:
                 if self.use_output_suffix and 'output_suffix' in resources and not self.output_base:
                     notebook_name += resources['output_suffix']
                 write_results = self.writer.write(output, resources, notebook_name=notebook_name)
 
                 #Post-process if post processor has been defined.
                 if hasattr(self, 'postprocessor') and self.postprocessor:
                     self.postprocessor(write_results)
                 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/writers/files.py

@@ -1,131 +1,135 b''
 """Contains writer for writing nbconvert output to filesystem."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import io
 import os
 import glob
 
 from IPython.utils.traitlets import Unicode
 from IPython.utils.path import link_or_copy, ensure_dir_exists
 from IPython.utils.py3compat import unicode_type
 
 from .base import WriterBase
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class FilesWriter(WriterBase):
     """Consumes nbconvert output and produces files."""
 
 
     build_directory = Unicode("", config=True,
                               help="""Directory to write output to.  Leave blank
                               to output to the current directory""")
 
     relpath = Unicode(
         "", config=True, 
         help="""When copying files that the notebook depends on, copy them in
         relation to this path, such that the destination filename will be
         os.path.relpath(filename, relpath). If FilesWriter is operating on a
         notebook that already exists elsewhere on disk, then the default will be
         the directory containing that notebook.""")
 
 
     # Make sure that the output directory exists.
     def _build_directory_changed(self, name, old, new):
         if new:
             ensure_dir_exists(new)
 
 
     def __init__(self, **kw):
         super(FilesWriter, self).__init__(**kw)
         self._build_directory_changed('build_directory', self.build_directory, 
                                       self.build_directory)
     
     def _makedir(self, path):
         """Make a directory if it doesn't already exist"""
         if path:
             self.log.info("Making directory %s", path)
             ensure_dir_exists(path)
 
     def write(self, output, resources, notebook_name=None, **kw):
             """
             Consume and write Jinja output to the file system.  Output directory
             is set via the 'build_directory' variable of this instance (a 
             configurable).
 
             See base for more...
             """
 
             # Verify that a notebook name is provided.
             if notebook_name is None:
                 raise TypeError('notebook_name')
 
             # Pull the extension and subdir from the resources dict.
             output_extension = resources.get('output_extension', None)
 
             # Get the relative path for copying files
             if self.relpath == '':
                 relpath = resources.get('metadata', {}).get('path', '')
             else:
                 relpath = self.relpath
 
             # Write all of the extracted resources to the destination directory.
             # NOTE: WE WRITE EVERYTHING AS-IF IT'S BINARY.  THE EXTRACT FIG
             # PREPROCESSOR SHOULD HANDLE UNIX/WINDOWS LINE ENDINGS...
-            for filename, data in resources.get('outputs', {}).items():
+
+            items = resources.get('outputs', {}).items()
+            if items:
+                self.log.info("Support files will be in %s", os.path.join(resources['output_files_dir'], ''))
+            for filename, data in items:
 
                 # Determine where to write the file to
                 dest = os.path.join(self.build_directory, filename)
                 path = os.path.dirname(dest)
                 self._makedir(path)
 
                 # Write file
                 self.log.debug("Writing %i bytes to support file %s", len(data), dest)
                 with io.open(dest, 'wb') as f:
                     f.write(data)
 
             # Copy referenced files to output directory
             if self.build_directory:
                 for filename in self.files:
 
                     # Copy files that match search pattern
                     for matching_filename in glob.glob(filename):
 
                         # compute the relative path for the filename
                         if relpath != '':
                             dest_filename = os.path.relpath(matching_filename, relpath)
                         else:
                             dest_filename = matching_filename
 
                         # Make sure folder exists.
                         dest = os.path.join(self.build_directory, dest_filename)
                         path = os.path.dirname(dest)
                         self._makedir(path)
 
                         # Copy if destination is different.
                         if not os.path.normpath(dest) == os.path.normpath(matching_filename):
                             self.log.info("Linking %s -> %s", matching_filename, dest)
                             link_or_copy(matching_filename, dest)
 
             # Determine where to write conversion results.
             if output_extension is not None:
                 dest = notebook_name + output_extension
             else:
                 dest = notebook_name
             if self.build_directory:
                 dest = os.path.join(self.build_directory, dest)
 
             # Write conversion results.
             self.log.info("Writing %i bytes to %s", len(output), dest)
             if isinstance(output, unicode_type):
                 with io.open(dest, 'w', encoding='utf-8') as f:
                     f.write(output)
             else:
                 with io.open(dest, 'wb') as f:
                     f.write(output)
                 
             return dest