Merge pull request #1 from minrk/nbconvert

Cleanup on NbConvertApp

IPython/nbconvert/exporters/__init__.py

@@ -1,11 +1,11 b''
 from .basichtml import BasicHTMLExporter
 from .export import *
 from .exporter import Exporter
 from .fullhtml import FullHTMLExporter
 from .reveal import RevealExporter
 from .latex import LatexExporter
 from .markdown import MarkdownExporter
 from .python import PythonExporter
-from .rst import RstExporter
+from .rst import RSTExporter
 from .sphinx_howto import SphinxHowtoExporter
 from .sphinx_manual import SphinxManualExporter

IPython/nbconvert/exporters/export.py

@@ -1,226 +1,226 b''
 """
 Module containing single call export functions.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from functools import wraps
 
 from IPython.nbformat.v3.nbbase import NotebookNode
 from IPython.config import Config
 
 from .exporter import Exporter
 from .basichtml import BasicHTMLExporter
 from .fullhtml import FullHTMLExporter
 from .latex import LatexExporter
 from .markdown import MarkdownExporter
 from .python import PythonExporter
 from .reveal import RevealExporter
-from .rst import RstExporter
+from .rst import RSTExporter
 from .sphinx_howto import SphinxHowtoExporter
 from .sphinx_manual import SphinxManualExporter
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
-def DocDecorator(f):    
+def DocDecorator(f):
     
     #Set docstring of function
     f.__doc__ = f.__doc__ + """
     nb : Notebook node
     config : config (optional, keyword arg)
         User configuration instance.
     resources : dict (optional, keyword arg)
         Resources used in the conversion process.
         
     Returns
     ----------
     tuple- output, resources, exporter_instance
     output : str
         Jinja 2 output.  This is the resulting converted notebook.
     resources : dictionary
         Dictionary of resources used prior to and during the conversion 
         process.
     exporter_instance : Exporter
         Instance of the Exporter class used to export the document.  Useful
         to caller because it provides a 'file_extension' property which
         specifies what extension the output should be saved as."""
             
     @wraps(f)
     def decorator(*args, **kwargs):
         return f(*args, **kwargs)
     
     return decorator
 
 
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
 
 __all__ = [
     'export',
     'export_sphinx_manual',
     'export_sphinx_howto',
     'export_basic_html',
     'export_full_html',
     'export_latex',
     'export_markdown',
     'export_python',
     'export_reveal',
     'export_rst',
     'export_by_name',
     'get_export_names',
     'ExporterNameError'
 ]
 
 
 class ExporterNameError(NameError):
     pass
 
 
 @DocDecorator
 def export(exporter, nb, **kw):
     """
     Export a notebook object using specific exporter class.
     
     exporter : Exporter class type or instance
         Class type or instance of the exporter that should be used.  If the 
         method initializes it's own instance of the class, it is ASSUMED that 
         the class type provided exposes a constructor (__init__) with the same 
         signature as the base Exporter class.
     """
     
     #Check arguments
     if exporter is None:
         raise TypeError("Exporter is None")
     elif not isinstance(exporter, Exporter) and not issubclass(exporter, Exporter):
         raise TypeError("exporter does not inherit from Exporter (base)")
     if nb is None:
         raise TypeError("nb is None")
     
     #Create the exporter
     resources = kw.pop('resources', None)
     if isinstance(exporter, Exporter):
         exporter_instance = exporter
     else:
         exporter_instance = exporter(**kw)
 
     #Try to convert the notebook using the appropriate conversion function.
     if isinstance(nb, NotebookNode):
         output, resources = exporter_instance.from_notebook_node(nb, resources)
     elif isinstance(nb, basestring):
         output, resources = exporter_instance.from_filename(nb, resources)
     else:
         output, resources = exporter_instance.from_file(nb, resources)
     return output, resources
 
 
 @DocDecorator
 def export_sphinx_manual(nb, **kw):
     """
     Export a notebook object to Sphinx Manual LaTeX
     """
     return export(SphinxManualExporter, nb, **kw)
 
 
 @DocDecorator
 def export_sphinx_howto(nb, **kw):
     """
     Export a notebook object to Sphinx HowTo LaTeX
     """
     return export(SphinxHowtoExporter, nb, **kw)
 
 
 @DocDecorator
 def export_basic_html(nb, **kw):
     """
     Export a notebook object to Basic HTML
     """
     return export(BasicHTMLExporter, nb, **kw)
 
 
 @DocDecorator
 def export_full_html(nb, **kw):
     """
     Export a notebook object to Full HTML
     """
     return export(FullHTMLExporter, nb, **kw)
 
 
 @DocDecorator
 def export_latex(nb, **kw):
     """
     Export a notebook object to LaTeX
     """
     return export(LatexExporter, nb, **kw)
 
 
 @DocDecorator
 def export_markdown(nb, **kw):
     """
     Export a notebook object to Markdown
     """
     return export(MarkdownExporter, nb, **kw)
 
 
 @DocDecorator
 def export_python(nb, **kw):
     """
     Export a notebook object to Python
     """
     return export(PythonExporter, nb, **kw)
 
 
 @DocDecorator
 def export_reveal(nb, **kw):
     """
-    Export a notebook object to Reveal
+    Export a notebook object to a Reveal.js presentation
     """
     return export(RevealExporter, nb, **kw)
 
 
 @DocDecorator
 def export_rst(nb, **kw):
     """
-    Export a notebook object to RST
+    Export a notebook object to reStructuredText
     """
-    return export(RstExporter, nb, **kw)
+    return export(RSTExporter, nb, **kw)
 
 
 @DocDecorator
 def export_by_name(format_name, nb, **kw):
     """
     Export a notebook object to a template type by its name.  Reflection
     (Inspect) is used to find the template's corresponding explicit export
     method defined in this module.  That method is then called directly.
     
     format_name : str
         Name of the template style to export to.
     """
     
     function_name = "export_" + format_name.lower()
     
     if function_name in globals():
         return globals()[function_name](nb, **kw)
     else:
         raise ExporterNameError("template for `%s` not found" % function_name)
 
 
 def get_export_names():
     "Return a list of the currently supported export targets"
     # grab everything after 'export_'
     l = [x[len('export_'):] for x in __all__ if x.startswith('export_')]
     
     # filter out the one method that is not a template
     l = [x for x in l if 'by_name' not in x]
     return sorted(l)

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):
+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.merge(super(RstExporter,self).default_config)
+        c.merge(super(RSTExporter,self).default_config)
         return c

IPython/nbconvert/nbconvertapp.py

@@ -1,197 +1,229 b''
 #!/usr/bin/env python
-"""NBConvert is a utility for conversion of IPYNB files.
+"""NBConvert is a utility for conversion of .ipynb files.
 
-Commandline interface for the NBConvert conversion utility.  Read the
-readme.rst for usage information
+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
-from IPython.config.application import catch_config_error
-from IPython.utils.traitlets import Unicode, List, Instance, DottedObjectName, Type
+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 .exporters.exporter import Exporter
-from .writers.base import WriterBase
+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).
-        An ipython config file can be used to batch convert notebooks in the 
-        current directory.""")
+        u"""This application is used to convert notebook files (*.ipynb)
+        to various other formats.""")
 
     examples = Unicode(u"""
-        Running `ipython nbconvert` will read the directory config file and then 
-        apply it to one or more notebooks.
-
+        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
-        > ipython nbconvert # this will use the config file to fill in the notebooks
-        """)
-    
+        
+        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 in self.writer_aliases:
             new = self.writer_aliases[new]
         self.writer_factory = import_item(new)
 
 
     #Other configurable variables
-    export_format = Unicode(
-        "", config=True,
-        help="""If specified, nbconvert will convert the document(s) specified
-                using this format.""")
+    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.
-                     Search patterns are supported.""")
-
-    nbconvert_aliases = {'format':'NbConvertApp.export_format',
-               'notebooks':'NbConvertApp.notebooks',
-               'writer':'NbConvertApp.writer_class'} 
-
+                     Wildcards are supported.
+                     Filenames passed positionally will be added to the list.
+                     """)
 
     @catch_config_error
     def initialize(self, argv=None):
-        self.aliases.update(self.nbconvert_aliases)
-
         super(NbConvertApp, self).initialize(argv)
-
-        #Register class here to have help with help all
-        self.classes.insert(0, Exporter)
-        self.classes.insert(0, WriterBase)
-        self.classes.insert(0, NbConvertBase)
-
-        #Init
-        self.init_config(self.extra_args)
+        self.init_notebooks()
         self.init_writer()
 
-
-    def init_config(self, extra_args):
-        """
-        Add notebooks to the config if needed.  Glob each notebook to replace
-        notebook patterns with filenames.
+    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.
         """
 
-        #Get any additional notebook patterns from the commandline
-        if len(extra_args) > 0:
-            for pattern in extra_args:
-                self.notebooks.append(pattern)
+        # 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 self.notebooks:
+        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, argv=None):
+    def start(self):
         """
-        Ran after initiialization completed
+        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
 
             #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)
             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:
 
             #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.
             else:
                 print('For help, use "ipython nbconvert --help"')
 
 
 #-----------------------------------------------------------------------------
 # Main entry point
 #-----------------------------------------------------------------------------
 
 launch_new_instance = NbConvertApp.launch_instance

IPython/nbconvert/transformers/__init__.py

@@ -1,12 +1,12 b''
 # Class base Transformers
-from .base import ConfigurableTransformer
+from .base import Transformer
 from .convertfigures import ConvertFiguresTransformer
 from .svg2pdf import SVG2PDFTransformer
 from .extractfigure import ExtractFigureTransformer
 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/base.py

@@ -1,109 +1,109 b''
 """
 Module that re-groups transformer that would be applied to ipynb files
 before going through the templating machinery.
 
 It exposes a convenient class to inherit from to access configurability.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from ..utils.base import NbConvertBase
 from IPython.utils.traitlets import Bool
 
 #-----------------------------------------------------------------------------
 # Classes and Functions
 #-----------------------------------------------------------------------------
 
-class ConfigurableTransformer(NbConvertBase):
+class Transformer(NbConvertBase):
     """ A configurable transformer
 
     Inherit from this class if you wish to have configurability for your
     transformer.
 
     Any configurable traitlets this class exposed will be configurable in profiles
     using c.SubClassName.atribute=value
 
     you can overwrite transform_cell to apply a transformation independently on each cell
     or __call__ if you prefer your own logic. See corresponding docstring for informations.
 
     Disabled by default and can be enabled via the config by
         'c.YourTransformerName.enabled = True'
     """
     
     enabled = Bool(False, config=True)
 
     def __init__(self, **kw):
         """
         Public constructor
         
         Parameters
         ----------
         config : Config
             Configuration file structure
         **kw : misc
             Additional arguments
         """
         
-        super(ConfigurableTransformer, self).__init__(**kw)
+        super(Transformer, self).__init__(**kw)
 
        
     def __call__(self, nb, resources):
         if self.enabled:
             return self.call(nb,resources)
         else:
             return nb, resources
 
 
     def call(self, nb, resources):
         """
         Transformation to apply on each notebook.
         
         You should return modified nb, resources.
         If you wish to apply your transform on each cell, you might want to 
         overwrite transform_cell method instead.
         
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
         try :
             for worksheet in nb.worksheets :
                 for index, cell in enumerate(worksheet.cells):
                     worksheet.cells[index], resources = self.transform_cell(cell, resources, index)
             return nb, resources
         except NotImplementedError:
             raise NotImplementedError('should be implemented by subclass')
 
 
     def transform_cell(self, cell, resources, index):
         """
         Overwrite if you want to apply a transformation on each cell.  You 
         should return modified cell and resource dictionary.
         
         Parameters
         ----------
         cell : NotebookNode cell
             Notebook cell being processed
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         index : int
             Index of the cell being processed
         """
 
         raise NotImplementedError('should be implemented by subclass')
         return cell, resources
 

IPython/nbconvert/transformers/convertfigures.py

@@ -1,79 +1,79 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 ConfigurableTransformer
+from .base import Transformer
 from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
-class ConvertFiguresTransformer(ConfigurableTransformer):
+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.
         for index, cell_out in enumerate(cell.get('outputs', [])):
             for data_type, data in cell_out.items():
 
                 #Get the name of the file exported by the extract figure 
                 #transformer.  Do not try to convert the figure if the extract
                 #fig transformer hasn't touched it
                 filename = cell_out.get(data_type + '_filename', None)
                 if filename:
                     figure_name = filename[:filename.rfind('.')]
                     self._convert_figure(cell_out, figure_name, resources, data_type, data)
         return cell, resources
 
 
     def _convert_figure(self, cell_out, resources, figure_name, data_type, data):
         """
         Convert a figure and output the results to the cell output
         """
 
         if not self.to_format in cell_out:
             if data_type == self.from_format:
                 filename = figure_name + '.' + self.to_format
                 if filename not in resources['figures']:
 
                     #On the cell, make the figure available via 
                     #   cell.outputs[i].pdf_filename  ... etc (PDF in example)
                     cell_out[self.to_format + '_filename'] = filename
 
                     #In the resources, make the figure available via
                     #   resources['figures']['filename'] = data
                     resources['figures'][filename] = self.convert_figure(data_type, data)

IPython/nbconvert/transformers/csshtmlheader.py

@@ -1,106 +1,106 b''
 """Module that pre-processes the notebook for export to HTML.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import io
 
 from pygments.formatters import HtmlFormatter
 
 from IPython.utils import path
 
-from .base import ConfigurableTransformer
+from .base import Transformer
 
 from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
-class CSSHTMLHeaderTransformer(ConfigurableTransformer):
+class CSSHTMLHeaderTransformer(Transformer):
     """
     Transformer used to pre-process notebook for HTML output.  Adds IPython notebook
     front-end CSS and Pygments CSS to HTML output.
     """
 
     header = []
 
     highlight_class = Unicode('.highlight', config=True,
                               help="CSS highlight class identifier")
 
     def __init__(self, config=None, **kw):
         """
         Public constructor
         
         Parameters
         ----------
         config : Config
             Configuration file structure
         **kw : misc
             Additional arguments
         """
         
         super(CSSHTMLHeaderTransformer, self).__init__(config=config, **kw)
 
         if self.enabled :
             self._regen_header()
 
 
     def __call__(self, nb, resources):
         """Fetch and add CSS to the resource dictionary
 
         Fetch CSS from IPython and Pygments to add at the beginning
         of the html files.  Add this css in resources in the 
         "inlining.css" key
         
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
         
         resources['inlining'] = {}
         resources['inlining']['css'] = self.header
         
         return nb, resources
 
 
     def _regen_header(self):
         """ 
         Fills self.header with lines of CSS extracted from IPython 
         and Pygments.
         """
         
         #Clear existing header.
         header = []
         
         #Construct path to IPy CSS
         sheet_filename = os.path.join(path.get_ipython_package_dir(), 
             'html', 'static', 'style', 'style.min.css')
         
         #Load style CSS file.
         with io.open(sheet_filename, encoding='utf-8') as file:
             file_text = file.read()
             header.append(file_text)
 
         #Add pygments CSS
         formatter = HtmlFormatter()
         pygments_css = formatter.get_style_defs(self.highlight_class)
         header.append(pygments_css)
 
         #Set header        
         self.header = header
 

IPython/nbconvert/transformers/extractfigure.py

@@ -1,90 +1,90 b''
 """Module containing a transformer that extracts all of the figures from the
 notebook file.  The extracted figures are returned in the 'resources' dictionary.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import sys
 from IPython.utils.traitlets import Unicode
-from .base import ConfigurableTransformer
+from .base import Transformer
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
-class ExtractFigureTransformer(ConfigurableTransformer):
+class ExtractFigureTransformer(Transformer):
     """
     Extracts all of the figures from the notebook file.  The extracted 
     figures 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.
         unique_key = resources.get('unique_key', 'figure')
         
         #Make sure figures key exists
         if not 'figures' in resources:
             resources['figures'] = {}
             
         #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 = data.decode('base64')
                     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( 
                                     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
 
                     #In the resources, make the figure available via
                     #   resources['figures']['filename'] = data
                     resources['figures'][figure_name] = data
 
         return cell, resources

IPython/nbconvert/transformers/latex.py

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

IPython/nbconvert/transformers/revealhelp.py

@@ -1,61 +1,61 b''
 """Module that pre-processes the notebook for export via Reveal.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
-from .base import ConfigurableTransformer
+from .base import Transformer
 from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
-class RevealHelpTransformer(ConfigurableTransformer):
+class RevealHelpTransformer(Transformer):
 
     url_prefix = Unicode('//cdn.jsdelivr.net/reveal.js/2.4.0',
                          config=True,
                          help="""If you want to use a local reveal.js library,
                          use 'url_prefix':'reveal.js' in your config object.""")
 
     def call(self, nb, resources):
         """
         Called once to 'transform' contents of the notebook.
 
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
 
         for worksheet in nb.worksheets :
             for index, cell in enumerate(worksheet.cells):
 
                 #Make sure the cell has slideshow metadata.
                 cell.metadata.align_type = cell.get('metadata', {}).get('slideshow', {}).get('align_type', 'Left')
                 cell.metadata.slide_type = cell.get('metadata', {}).get('slideshow', {}).get('slide_type', '-')
 
                 #Get the slide type.  If type is start of subslide or slide,
                 #end the last subslide/slide.
                 if cell.metadata.slide_type in ['slide']:
                     worksheet.cells[index - 1].metadata.slide_helper = 'slide_end'
                 if cell.metadata.slide_type in ['subslide']:
                     worksheet.cells[index - 1].metadata.slide_helper = 'subslide_end'
 
 
         if 'reveal' not in resources:
             resources['reveal'] = {}
         resources['reveal']['url_prefix'] = self.url_prefix
 
         return nb, resources

IPython/nbconvert/transformers/sphinx.py

@@ -1,264 +1,264 b''
 """Module that allows custom Sphinx parameters to be set on the notebook and
 on the 'other' object passed into Jinja.  Called prior to Jinja conversion
 process.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from __future__ import print_function, absolute_import
 
 # Stdlib imports
 # Used to find Sphinx package location
 import sphinx
 import os.path
 
 # Used to set the default date to today's date 
 from datetime import date 
 
 # Third-party imports
 # Needed for Pygments latex definitions.
 from pygments.formatters import LatexFormatter
 
 # Our own imports
 # Configurable traitlets
 from IPython.utils.traitlets import Unicode, Bool
 
 # Needed to override transformer
-from .base import (ConfigurableTransformer)
+from .base import (Transformer)
 
 from IPython.nbconvert.utils import console  
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
-class SphinxTransformer(ConfigurableTransformer):
+class SphinxTransformer(Transformer):
     """
     Sphinx utility transformer.
 
     This transformer is used to set variables needed by the latex to build
     Sphinx stylized templates.
     """
     
     interactive = Bool(False, config=True, help="""
         Allows you to define whether or not the Sphinx exporter will prompt
         you for input during the conversion process.  If this is set to false,
         the author, version, release, date, and chapter_style traits should
         be set.
         """)
     
     author = Unicode("Unknown Author", config=True, help="Author name")
     
     version = Unicode("", config=True, help="""
         Version number
         You can leave this blank if you do not want to render a version number.
         Example: "1.0.0"
         """)
     
     release = Unicode("", config=True, help="""
         Release name
         You can leave this blank if you do not want to render a release name.
         Example: "Rough Draft"
         """)
     
     publish_date = Unicode("", config=True, help="""
         Publish date
         This is the date to render on the document as the publish date.
         Leave this blank to default to todays date.  
         Example: "June 12, 1990"
         """)
     
     chapter_style = Unicode("Bjarne", config=True, help="""
         Sphinx chapter style
         This is the style to use for the chapter headers in the document.
         You may choose one of the following:
             "Bjarne"    (default)
             "Lenny"
             "Glenn"
             "Conny"
             "Rejne"
             "Sonny"    (used for international documents)
         """)
     
     output_style = Unicode("notebook", config=True, help="""
         Nbconvert Ipython
         notebook input/output formatting style.
         You may choose one of the following:
             "simple     (recommended for long code segments)"
             "notebook"  (default)
         """)
     
     center_output = Bool(False, config=True, help="""
         Optional attempt to center all output.  If this is false, no additional
         formatting is applied.
         """)
     
     use_headers = Bool(True, config=True, help="""
         Whether not a header should be added to the document.
         """)
     
     #Allow the user to override the title of the notebook (useful for
     #fancy document titles that the file system doesn't support.)
     overridetitle = Unicode("", config=True, help="")
 
     
     def call(self, nb, resources):
         """
         Sphinx transformation to apply on each notebook.
         
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
          
         # TODO: Add versatile method of additional notebook metadata.  Include
         #       handling of multiple files.  For now use a temporay namespace,
         #       '_draft' to signify that this needs to change.
         if not "sphinx" in resources:
             resources["sphinx"] = {}
 
         if self.interactive:
             
             # Prompt the user for additional meta data that doesn't exist currently
             # but would be usefull for Sphinx.
             resources["sphinx"]["author"] = self._prompt_author()
             resources["sphinx"]["version"] = self._prompt_version()
             resources["sphinx"]["release"] = self._prompt_release()
             resources["sphinx"]["date"] = self._prompt_date()
             
             # Prompt the user for the document style.
             resources["sphinx"]["chapterstyle"] = self._prompt_chapter_title_style()
             resources["sphinx"]["outputstyle"] = self._prompt_output_style()
             
             # Small options
             resources["sphinx"]["centeroutput"] = console.prompt_boolean("Do you want to center the output? (false)", False)
             resources["sphinx"]["header"] = console.prompt_boolean("Should a Sphinx document header be used? (true)", True)
         else:
             
             # Try to use the traitlets.
             resources["sphinx"]["author"] = self.author
             resources["sphinx"]["version"] = self.version
             resources["sphinx"]["release"] = self.release
             
             # Use todays date if none is provided.
             if self.publish_date:
                 resources["sphinx"]["date"] = self.publish_date
             elif len(resources['metadata']['modified_date'].strip()) == 0:
                 resources["sphinx"]["date"] = date.today().strftime("%B %-d, %Y")
             else:
                 resources["sphinx"]["date"] = resources['metadata']['modified_date']
             
             # Sphinx traitlets.
             resources["sphinx"]["chapterstyle"] = self.chapter_style
             resources["sphinx"]["outputstyle"] = self.output_style
             resources["sphinx"]["centeroutput"] = self.center_output
             resources["sphinx"]["header"] = self.use_headers
             
         # Find and pass in the path to the Sphinx dependencies.
         resources["sphinx"]["texinputs"] = os.path.realpath(os.path.join(sphinx.__file__, "..", "texinputs"))
         
         # Generate Pygments definitions for Latex 
         resources["sphinx"]["pygment_definitions"] = self._generate_pygments_latex_def()
         
         if not (self.overridetitle == None or len(self.overridetitle.strip()) == 0):
             resources['metadata']['name'] = self.overridetitle
         
         # End
         return nb, resources 
     
     
     def _generate_pygments_latex_def(self):
         """
         Generate the pygments latex definitions that allows pygments
         to work in latex.
         """
         
         return LatexFormatter().get_style_defs()       
     
     
     def _prompt_author(self):
         """
         Prompt the user to input an Author name
         """
         return  console.input("Author name: ")
     
     
     def _prompt_version(self):
         """
         prompt the user to enter a version number
         """
         return  console.input("Version (ie ""1.0.0""): ")
     
     
     def _prompt_release(self):
         """
         Prompt the user to input a release name
         """
         
         return  console.input("Release Name (ie ""Rough draft""): ")
     
     
     def _prompt_date(self, resources):
         """
         Prompt the user to enter a date
         """
         
         if resources['metadata']['modified_date']:
             default_date = resources['metadata']['modified_date']
         else:
             default_date = date.today().strftime("%B %-d, %Y")
             
         user_date = console.input("Date (deafults to \"" + default_date + "\"): ")
         if len(user_date.strip()) == 0:
             user_date = default_date
         return user_date
     
     
     def _prompt_output_style(self):
         """
         Prompts the user to pick an IPython output style.
         """
         
         # Dictionary of available output styles
         styles = {1: "simple",
                   2: "notebook"}
         
         #Append comments to the menu when displaying it to the user.
         comments = {1: "(recommended for long code segments)",
                     2: "(default)"}
         
         return console.prompt_dictionary(styles, default_style=2, menu_comments=comments)
     
     
     def _prompt_chapter_title_style(self):
         """
         Prompts the user to pick a Sphinx chapter style
         """
         
         # Dictionary of available Sphinx styles
         styles = {1: "Bjarne",
                   2: "Lenny",
                   3: "Glenn",
                   4: "Conny",
                   5: "Rejne",
                   6: "Sonny"}
         
         #Append comments to the menu when displaying it to the user.
         comments = {1: "(default)",
                     6: "(for international documents)"}
         
         return console.prompt_dictionary(styles, menu_comments=comments)