Merge pull request #3734 from jdfreder/file_subdir

Nbconvert: Export extracted files into `nbname_files` subdirectory

Default build directory changed to .
Files extracted from notebook now are placed into a ./notebook_files/ directory by default
Spaces added between # symbols and comments
It may be best to look at the diffs of the individual commits... The addition of spaces in the comments makes the overall diff hard to read.

IPython/nbconvert/exporters/exporter.py

@@ -1,443 +1,443 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,
         'markdown': filters.markdown2html,
         'ansi2html': filters.ansi2html,
         'filter_data_type': filters.DataTypeFilter,
         'get_lines': filters.get_lines,
         'highlight': filters.highlight,
         'highlight2html': filters.highlight,
         'highlight2latex': filters.highlight2latex,
         'markdown2latex': filters.markdown2latex,
         'markdown2rst': filters.markdown2rst,
         'pycomment': filters.python_comment,
         'rm_ansi': filters.remove_ansi,
         'rm_dollars': filters.strip_dollars,
         'rm_fake': filters.rm_fake,
         'html_text' : filters.html_text,
         'add_anchor': filters.add_anchor,
         'ansi2latex': filters.ansi2latex,
         'rm_math_space': filters.rm_math_space,
         'wrap': filters.wrap
 }
 
 #-----------------------------------------------------------------------------
 # 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.
     
     {filters}
     """
     
     # finish the docstring
     __doc__ = __doc__.format(filters = '- '+'\n    - '.join(default_filters.keys()))
 
 
     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(
         os.path.join("..", "templates"), config=True,
         help="Path where the template files are located.")
 
     template_skeleton_path = Unicode(
         os.path.join("..", "templates", "skeleton"), config=True,
         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.ExtractFigureTransformer,
+                                 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.
         """
         
         #Call the base class constructor
         c = self.default_config
         if config:
             c.merge(config)
 
         super(Exporter, self).__init__(config=c, **kw)
 
         #Init
         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
         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)
         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_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)
 
         loaders.append(FileSystemLoader([
                 os.path.join(here, self.template_path),
                 os.path.join(here, self.template_skeleton_path),
                 ]))
 
         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/latex.py

@@ -1,102 +1,102 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")
 
     template_file = Unicode(
         'base', config=True,
         help="Name of the template file to use")
 
     #Latex constants
     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)
 
 
     def _init_filters(self):
         """
         Register all of the filters required for the exporter.
         """
         
         #Register the filters of the base class.
         super(LatexExporter, self)._init_filters()
 
         #Add latex filters to the Jinja2 environment
         self.register_filter('escape_tex', filters.escape_latex) 
         self.register_filter('highlight', filters.highlight2latex) 
     
 
     @property
     def default_config(self):
         c = Config({
             'NbConvertBase': {
                 'display_data_priority' : ['latex', 'pdf', 'png', 'jpg', 'svg', 'jpeg', 'text']
                 },
-             'ExtractFigureTransformer': {
+             'ExtractOutputTransformer': {
                     'enabled':True
                  },
              'SVG2PDFTransformer': {
                     'enabled':True
                  },
              'LatexTransformer': {
                     'enabled':True
                  }
          })
         c.merge(super(LatexExporter,self).default_config)
         return c

IPython/nbconvert/exporters/rst.py

@@ -1,42 +1,42 b''
 """
 Exporter for exporting notebooks to restructured text.
 """
 #-----------------------------------------------------------------------------
 # 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.config import Config
 
 from .exporter import Exporter
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class RSTExporter(Exporter):
     """
     Exports restructured text documents.
     """
     
     file_extension = Unicode(
         'rst', config=True, 
         help="Extension of the file that should be written to disk")
 
     template_file = Unicode(
             'rst', config=True,
             help="Name of the template file to use")
 
     @property
     def default_config(self):
-        c = Config({'ExtractFigureTransformer':{'enabled':True}})
+        c = Config({'ExtractOutputTransformer':{'enabled':True}})
         c.merge(super(RSTExporter,self).default_config)
         return c

IPython/nbconvert/exporters/tests/test_exporter.py

@@ -1,113 +1,113 b''
 """
 Module with tests for exporter.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 IPython.config import Config
 
 from .base import ExportersTestsBase
 from .cheese import CheeseTransformer
 from ..exporter import Exporter
 
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class TestExporter(ExportersTestsBase):
     """Contains test functions for exporter.py"""
 
 
     def test_constructor(self):
         """
         Can an Exporter be constructed?
         """
         Exporter()
 
 
     def test_export(self):
         """
         Can an Exporter export something?
         """
         exporter = self._make_exporter()
         (output, resources) = exporter.from_filename(self._get_notebook())
         assert len(output) > 0
 
 
-    def test_extract_figures(self):
+    def test_extract_outputs(self):
         """
-        If the ExtractFigureTransformer is enabled, are figures extracted?
+        If the ExtractOutputTransformer is enabled, are outputs extracted?
         """
-        config = Config({'ExtractFigureTransformer': {'enabled': True}})
+        config = Config({'ExtractOutputTransformer': {'enabled': True}})
         exporter = self._make_exporter(config=config)
         (output, resources) = exporter.from_filename(self._get_notebook())
         assert resources is not None
-        assert 'figures' in resources
-        assert len(resources['figures']) > 0
+        assert 'outputs' in resources
+        assert len(resources['outputs']) > 0
 
 
     def test_transformer_class(self):
         """
         Can a transformer be added to the transformers list by class type?
         """
         config = Config({'Exporter': {'transformers': [CheeseTransformer]}})
         exporter = self._make_exporter(config=config)
         (output, resources) = exporter.from_filename(self._get_notebook())
         assert resources is not None
         assert 'cheese' in resources
         assert resources['cheese'] == 'real'
 
 
     def test_transformer_instance(self):
         """
         Can a transformer be added to the transformers list by instance?
         """
         config = Config({'Exporter': {'transformers': [CheeseTransformer()]}})
         exporter = self._make_exporter(config=config)
         (output, resources) = exporter.from_filename(self._get_notebook())
         assert resources is not None
         assert 'cheese' in resources
         assert resources['cheese'] == 'real'
 
 
     def test_transformer_dottedobjectname(self):
         """
         Can a transformer be added to the transformers list by dotted object name?
         """
         config = Config({'Exporter': {'transformers': ['IPython.nbconvert.exporters.tests.cheese.CheeseTransformer']}})
         exporter = self._make_exporter(config=config)
         (output, resources) = exporter.from_filename(self._get_notebook())
         assert resources is not None
         assert 'cheese' in resources
         assert resources['cheese'] == 'real'
 
 
     def test_transformer_via_method(self):
         """
         Can a transformer be added via the Exporter convinience method?
         """
         exporter = self._make_exporter()
         exporter.register_transformer(CheeseTransformer, enabled=True)
         (output, resources) = exporter.from_filename(self._get_notebook())
         assert resources is not None
         assert 'cheese' in resources
         assert resources['cheese'] == 'real'
 
 
     def _make_exporter(self, config=None):
         #Create the exporter instance, make sure to set a template name since
         #the base Exporter doesn't have a template associated with it.
         exporter = Exporter(config=config)
         exporter.template_file = 'python'
         return exporter        
  No newline at end of file

IPython/nbconvert/nbconvertapp.py

@@ -1,229 +1,230 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
+# Stdlib imports
 from __future__ import print_function
 import sys
 import os
 import glob
 
-#From IPython
+# 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
 
 #-----------------------------------------------------------------------------
 #Classes and functions
 #-----------------------------------------------------------------------------
 
 nbconvert_aliases = {}
 nbconvert_aliases.update(base_aliases)
 nbconvert_aliases.update({
     'format' : 'NbConvertApp.export_format',
     '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."
         )
 })
 
 
 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 `--format`.
         Options include {0}
         
         > ipython nbconvert --format latex mynotebook.ipnynb
         
         You can also pipe the output to stdout, rather than a file
         
         > ipython nbconvert mynotebook.ipynb --stdout
         
         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 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 in self.writer_aliases:
             new = self.writer_aliases[new]
         self.writer_factory = import_item(new)
 
 
-    #Other configurable variables
+    # Other configurable variables
     export_format = CaselessStrEnum(get_export_names(),
         default_value="full_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_notebooks()
         self.init_writer()
 
     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.
+        # Use glob to replace all the notebook patterns with filenames.
         filenames = []
         for pattern in patterns:
             for filename in glob.glob(pattern):
                 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
+        # 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.
+            # 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 to export
             try:
                 output, resources = export_by_name(self.export_format,
                                               notebook_filename, 
                                               resources=resources,
                                               config=self.config)
             except ExporterNameError as e:
                 print("Error: '%s' exporter not found." % self.export_format,
                       file=sys.stderr)
                 print("Known exporters are:",
                       "\n\t" + "\n\t".join(get_export_names()),
                       file=sys.stderr)
                 sys.exit(-1)
-            #except Exception as e:
-                #print("Error: could not export '%s'" % notebook_filename, file=sys.stderr)
-                #print(e, file=sys.stderr)
+            # except Exception as e:
+                # print("Error: could not export '%s'" % notebook_filename, file=sys.stderr)
+                # print(e, file=sys.stderr)
             else:
                 self.writer.write(output, resources, notebook_name=notebook_name)
                 conversion_success += 1
 
-        #If nothing was converted successfully, help the user.
+        # If nothing was converted successfully, help the user.
         if conversion_success == 0:
 
-            #No notebooks were specified, show help.
+            # No notebooks were specified, show help.
             if len(self.notebooks) == 0:
                 self.print_help()
 
-            #Notebooks were specified, but not converted successfully.  Show how
-            #to access help.
+            # Notebooks were specified, but not converted successfully.  Show how
+            # to access help.
             else:
                 print('For help, use "ipython nbconvert --help"')
 
 
 #-----------------------------------------------------------------------------
 # Main entry point
 #-----------------------------------------------------------------------------
 
 launch_new_instance = NbConvertApp.launch_instance

IPython/nbconvert/tests/test_nbconvertapp.py

@@ -1,123 +1,123 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
+# 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', 
                 '--format="python"', '--notebooks=["*.ipynb"]']).lower()
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook1.py'))
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook2.py'))
+            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', '--format="python"', 
                 '--notebooks=["%s"]' % os.path.join('subdir', '*.ipynb')]).lower()
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook1.py'))
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook2.py'))
+            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', '--format="python"', 
                 '--notebooks=["notebook2.ipynb"]']).lower()
-            assert not os.path.isfile(os.path.join('nbconvert_build', 'notebook1.py'))
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook2.py'))
+            assert not os.path.isfile('notebook1.py')
+            assert os.path.isfile('notebook2.py')
 
 
     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', '--format="python"', 
                 '--notebooks=["*.ipynb", "notebook1.ipynb", "notebook2.ipynb"]']).lower()
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook1.py'))
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook2.py'))
+            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', '--format="python"', 
                 '--notebooks=["notebook1.ipynb", "notebook2.ipynb", "*.ipynb"]']).lower()
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook1.py'))
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook2.py'))
+            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(os.path.join('nbconvert_build', 'notebook1.py'))
-            assert not os.path.isfile(os.path.join('nbconvert_build', 'notebook2.py'))
+            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(os.path.join('nbconvert_build', 'notebook1.py'))
-            assert os.path.isfile(os.path.join('nbconvert_build', 'notebook2.py'))
+            assert not os.path.isfile('notebook1.py')
+            assert os.path.isfile('notebook2.py')

IPython/nbconvert/transformers/__init__.py

@@ -1,12 +1,12 b''
 # Class base Transformers
 from .base import Transformer
 from .convertfigures import ConvertFiguresTransformer
 from .svg2pdf import SVG2PDFTransformer
-from .extractfigure import ExtractFigureTransformer
+from .extractoutput import ExtractOutputTransformer
 from .revealhelp import RevealHelpTransformer
 from .latex import LatexTransformer
 from .sphinx import SphinxTransformer
 from .csshtmlheader import CSSHTMLHeaderTransformer
 
 # decorated function Transformers
 from .coalescestreams import coalesce_streams

IPython/nbconvert/transformers/convertfigures.py

@@ -1,64 +1,64 b''
 """Module containing a transformer that converts outputs in the notebook from 
 one format to another.
 """
 #-----------------------------------------------------------------------------
 # 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 Transformer
 from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class ConvertFiguresTransformer(Transformer):
     """
     Converts all of the outputs in a notebook from one format to another.
     """
 
     from_format = Unicode(config=True, help='Format the converter accepts')
     to_format = Unicode(config=True, help='Format the converter writes')
 
     def __init__(self, **kw):
         """
         Public constructor
         """
         super(ConvertFiguresTransformer, self).__init__(**kw)
 
 
     def convert_figure(self, data_format, data):
         raise NotImplementedError()
 
 
     def transform_cell(self, cell, resources, cell_index):
         """
         Apply a transformation on each cell,
         
         See base.py
         """
 
-        #Loop through all of the datatypes of the outputs in the cell.
+        # Loop through all of the datatypes of the outputs in the cell.
         for index, cell_out in enumerate(cell.get('outputs', [])):
             for data_type, data in cell_out.items():
-                # this must run *before* extract figures,
+                # this must run *before* extract outputs,
                 # so figure_name and filename do not exist
                 self._convert_figure(cell_out, resources, data_type, data)
         return cell, resources
 
 
     def _convert_figure(self, cell_out, resources, data_type, data):
         """
         Convert a figure and output the results to the cell output
         """
         if not self.to_format in cell_out and data_type == self.from_format:
             data = self.convert_figure(data_type, data)
             cell_out[self.to_format] = data

IPython/nbconvert/transformers/extractoutput.py

@@ -1,96 +1,101 b''
-"""Module containing a transformer that extracts all of the figures from the
-notebook file.  The extracted figures are returned in the 'resources' dictionary.
+"""Module containing a transformer that extracts all of the outputs from the
+notebook file.  The extracted outputs are returned in the 'resources' dictionary.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import base64
 import sys
+import os
 
 from IPython.utils.traitlets import Unicode
 from .base import Transformer
 from IPython.utils import py3compat
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
-class ExtractFigureTransformer(Transformer):
+class ExtractOutputTransformer(Transformer):
     """
-    Extracts all of the figures from the notebook file.  The extracted 
-    figures are returned in the 'resources' dictionary.
+    Extracts all of the outputs from the notebook file.  The extracted 
+    outputs are returned in the 'resources' dictionary.
     """
 
     figure_filename_template = Unicode(
         "{unique_key}_{cell_index}_{index}.{extension}", config=True)
 
 
     def transform_cell(self, cell, resources, cell_index):
         """
         Apply a transformation on each cell,
         
         Parameters
         ----------
         cell : NotebookNode cell
             Notebook cell being processed
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         cell_index : int
             Index of the cell being processed (see base.py)
         """
 
         #Get the unique key from the resource dict if it exists.  If it does not 
-        #exist, use 'figure' as the default.
+        #exist, use 'figure' as the default.  Also, get files directory if it
+        #has been specified
         unique_key = resources.get('unique_key', 'figure')
+        output_files_dir = resources.get('output_files_dir', None)
         
-        #Make sure figures key exists
-        if not 'figures' in resources:
-            resources['figures'] = {}
+        #Make sure outputs key exists
+        if not 'outputs' in resources:
+            resources['outputs'] = {}
             
         #Loop through all of the outputs in the cell
         for index, out in enumerate(cell.get('outputs', [])):
 
             #Get the output in data formats that the template is interested in.
             for out_type in self.display_data_priority:
                 if out.hasattr(out_type):
                     data = out[out_type]
 
                     #Binary files are base64-encoded, SVG is already XML
                     if out_type in ('png', 'jpg', 'jpeg', 'pdf'):
                         # data is b64-encoded as text (str, unicode)
                         # decodestring only accepts bytes
                         data = py3compat.cast_bytes(data)
                         data = base64.decodestring(data)
                     elif sys.platform == 'win32':
                         data = data.replace('\n', '\r\n').encode("UTF-8")
                     else:
                         data = data.encode("UTF-8")
                     
                     #Build a figure name
-                    figure_name = self.figure_filename_template.format( 
+                    filename = self.figure_filename_template.format( 
                                     unique_key=unique_key,
                                     cell_index=cell_index,
                                     index=index,
                                     extension=out_type)
 
                     #On the cell, make the figure available via 
                     #   cell.outputs[i].svg_filename  ... etc (svg in example)
                     # Where
                     #   cell.outputs[i].svg  contains the data
-                    out[out_type + '_filename'] = figure_name
+                    if output_files_dir is not None:
+                        filename = os.path.join(output_files_dir, filename)
+                    out[out_type + '_filename'] = filename
 
                     #In the resources, make the figure available via
-                    #   resources['figures']['filename'] = data
-                    resources['figures'][figure_name] = data
+                    #   resources['outputs']['filename'] = data
+                    resources['outputs'][filename] = data
 
         return cell, resources

IPython/nbconvert/writers/debug.py

@@ -1,43 +1,43 b''
 #!/usr/bin/env python
 """
 Contains debug writer.
 """
 #-----------------------------------------------------------------------------
 #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 WriterBase
 from pprint import pprint
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class DebugWriter(WriterBase):
     """Consumes output from nbconvert export...() methods and writes usefull
     debugging information to the stdout.  The information includes a list of
     resources that were extracted from the notebook(s) during export."""
 
 
     def write(self, output, resources, notebook_name='notebook', **kw):
         """
         Consume and write Jinja output.
 
         See base for more...
         """
 
-        if 'figures' in resources:
-            print("Figures extracted from %s" % notebook_name)
+        if 'outputs' in resources:
+            print("outputs extracted from %s" % notebook_name)
             print('-' * 80)
-            pprint.pprint(resources['figures'], indent=2, width=70)
+            pprint.pprint(resources['outputs'], indent=2, width=70)
         else:
-            print("No figures extracted from %s" % notebook_name)
+            print("No outputs extracted from %s" % notebook_name)
         print('=' * 80)

IPython/nbconvert/writers/files.py

@@ -1,98 +1,102 b''
 #!/usr/bin/env python
 """
 Contains writer for writing nbconvert output to filesystem.
 """
 #-----------------------------------------------------------------------------
 #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 io
 import os
 import shutil
 import glob
 
 from IPython.utils.traitlets import Unicode
 
 from .base import WriterBase
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class FilesWriter(WriterBase):
     """Consumes nbconvert output and produces files."""
 
 
-    build_directory = Unicode("nbconvert_build", config=True, 
+    build_directory = Unicode(".", config=True, 
                               help="""Directory to write output to.  Leave blank
                               to output to the current directory""")
 
 
-    #Make sure that the output directory exists.
+    # Make sure that the output directory exists.
     def _build_directory_changed(self, name, old, new):
         if new and not os.path.isdir(new):
             os.makedirs(new)
 
 
     def __init__(self, **kw):
         super(FilesWriter, self).__init__(**kw)
         self._build_directory_changed('build_directory', self.build_directory, 
                                       self.build_directory)
 
 
     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...
             """
 
-            #Pull the extension from the resources dict.
+            # Pull the extension and subdir from the resources dict.
             output_extension = resources['output_extension']
 
-            #Write all of the extracted resources to the destination directory.
-            #NOTE: WE WRITE EVERYTHING AS-IF IT'S BINARY.  THE EXTRACT FIG
-            #TRANSFORMER SHOULD HANDLE UNIX/WINDOWS LINE ENDINGS...
-            for filename, data in resources.get('figures', {}).items():
+            # Write all of the extracted resources to the destination directory.
+            # NOTE: WE WRITE EVERYTHING AS-IF IT'S BINARY.  THE EXTRACT FIG
+            # TRANSFORMER SHOULD HANDLE UNIX/WINDOWS LINE ENDINGS...
+            for filename, data in resources.get('outputs', {}).items():
 
-                #Determine where to write the file to
+                # Determine where to write the file to
                 dest = os.path.join(self.build_directory, filename)
+                path = os.path.dirname(dest)
+                if not os.path.isdir(path):
+                    os.makedirs(path)
 
-                #Write file
+                # Write file
                 with io.open(dest, 'wb') as f:
                     f.write(data)
 
-            #Copy referenced files to output directory
+            # Copy referenced files to output directory
             if self.build_directory:
                 for filename in self.files:
 
-                    #Copy files that match search pattern
+                    # Copy files that match search pattern
                     for matching_filename in glob.glob(filename):
 
-                        #Make sure folder exists.
+                        # Make sure folder exists.
                         dest = os.path.join(self.build_directory, filename)
                         path = os.path.dirname(dest)
                         if not os.path.isdir(path):
                             os.makedirs(path)
 
-                        #Copy
-                        shutil.copyfile(matching_filename, dest)
+                        # Copy if destination is different.
+                        if not os.path.normpath(dest) == os.path.normpath(matching_filename):
+                            shutil.copyfile(matching_filename, dest)
 
-            #Determine where to write conversion results.
+            # Determine where to write conversion results.
             dest = notebook_name + '.' + output_extension
             if self.build_directory:
                 dest = os.path.join(self.build_directory, dest)
 
-            #Write conversion results.
+            # Write conversion results.
             with io.open(dest, 'w') as f:
                 f.write(output)

IPython/nbconvert/writers/stdout.py

@@ -1,37 +1,35 b''
 #!/usr/bin/env python
 """
 Contains Stdout writer
 """
 #-----------------------------------------------------------------------------
 #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 WriterBase
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class StdoutWriter(WriterBase):
     """Consumes output from nbconvert export...() methods and writes to the 
-    stdout stream.  Allows for quick debuging of nbconvert output.  Using the
-    debug flag makes the writer pretty-print the figures contained within the
-    notebook."""
+    stdout stream."""
 
 
     def write(self, output, resources, **kw):
         """
         Consume and write Jinja output.
 
         See base for more...
         """
 
         print(output)