Cleanup and refactor of API, almost complete.

Still need to target exporter.py and convert.py
Then one last run-trough.

nbconvert/api/basichtml.py

@@ -1,4 +1,5 b''
-"""TODO: Docstring
+"""
+Exporter that exports Basic HTML.
 """
 
 #-----------------------------------------------------------------------------
@@ -13,16 +14,25 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
+import nbconvert.transformers.csshtmlheader
+
 # local import
 import exporter
-import nbconvert.transformers.csshtmlheader
-from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
-class BasicHtmlExporter(exporter.Exporter):
 
+class BasicHtmlExporter(exporter.Exporter):
+    """
+    Exports a basic HTML document.  This exporter assists with the export of
+    HTML.  Inherit from it if you are writing your own HTML template and need
+    custom tranformers/filters.  If you don't need custom tranformers/
+    filters, just change the 'template_file' config option.  
+    """
+    
     file_extension = Unicode(
         'html', config=True, 
         help="Extension of the file that should be written to disk"

nbconvert/api/convert.py

@@ -1,7 +1,5 b''
-"""Latex transformer.
-
-Module that allows latex output notebooks to be conditioned before
-they are converted.
+"""
+Module containing easy to use conversion functions.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
@@ -42,10 +40,12 b' def export(nb, config=None, transformers=None, filters=None, exporter_type=Expor'
         output, resources = exporter_instance.from_file(nb)
     return output, resources, exporter_instance
 
+
 def load_class(template_name):
     class_name = template_name[0].upper() + template_name[1:] + "Exporter"
     module = __import__('nbconvert.api.' + template_name, fromlist=[class_name])                                       
     return getattr(module, class_name)
 
+
 def export_by_name(nb, template_name, config=None, transformers=None, filters=None):
     return export(nb, config, transformers, filters, load_class(template_name))
  No newline at end of file

nbconvert/api/exporter.py

@@ -18,6 +18,7 b' before conversion and jinja filter that would then be available in the templates'
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
+
 from __future__ import print_function, absolute_import
 
 # Stdlib imports
@@ -59,16 +60,10 b' TEMPLATE_SKELETON_PATH = "/../templates/skeleton/"'
 JINJA_EXTENSIONS = ['jinja2.ext.loopcontrols']
 
 #-----------------------------------------------------------------------------
-# Classes and functions
+# Class
 #-----------------------------------------------------------------------------
+
 class Exporter(Configurable):
-    pre_transformer_order = List(['haspyout_transformer'],
-        config=True,
-        help= """
-            An ordered list of pre-transformer to apply to the IPYNB
-            file before running through templates
-            """
-        )
 
     template_file = Unicode(
             '', config=True,
@@ -88,7 +83,7 b' class Exporter(Configurable):'
 
     # Public Constructor #####################################################
     
-    def __init__(self, preprocessors=None, jinja_filters=None, config=None, **kw):
+    def __init__(self, transformers=None, filters=None, config=None, **kw):
     
         #Call the base class constructor
         super(Exporter, self).__init__(config=config, **kw)
@@ -96,24 +91,20 b' class Exporter(Configurable):'
         #Standard environment
         self._init_environment()
 
-        #TODO: Implement reflection style methods to get user transformers.
-        #if not preprocessors is None:        
-        #    for name in self.pre_transformer_order:
-        #        # get the user-defined transformer first
-        #        transformer = preprocessors.get(name, getattr(trans, name, None))
-        #        if isinstance(transformer, MetaHasTraits):
-        #            transformer = transformer(config=config)
-        #        self.preprocessors.append(transformer)
-
         #Add transformers
         self._register_transformers()
 
         #Add filters to the Jinja2 environment
         self._register_filters()
 
+        #Load user transformers.  Overwrite existing transformers if need be.
+        if not transformers is None:        
+            for transformer in transformers:
+                self.register_transformer(transformer)
+                
         #Load user filters.  Overwrite existing filters if need be.
-        if not jinja_filters is None:
-            for key, user_filter in jinja_filters.iteritems():
+        if not filters is None:
+            for key, user_filter in filters.iteritems():
                 if issubclass(user_filter, MetaHasTraits):
                     self.environment.filters[key] = user_filter(config=config)
                 else:

nbconvert/api/fullhtml.py

@@ -1,4 +1,5 b''
-"""TODO: Docstring
+"""
+Exporter for exporting full HTML documents.
 """
 
 #-----------------------------------------------------------------------------
@@ -13,15 +14,20 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
 # local import
 import basichtml.BasicHtmlExporter
-from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
-class FullHtmlExporter(basichtml.BasicHtmlExporter):
 
+class FullHtmlExporter(basichtml.BasicHtmlExporter):
+    """
+    Exports a full HTML document.
+    """
+    
     template_file = Unicode(
             'fullhtml', config=True,
             help="Name of the template file to use")    
  No newline at end of file

nbconvert/api/latex.py

@@ -1,3 +1,9 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.
 #
@@ -19,11 +25,13 b' from IPython.utils.traitlets import Unicode'
 # other libs/dependencies
 from jinja2 import Environment, FileSystemLoader
 
-# local import
-import exporter
 import nbconvert.filters.latex
 import nbconvert.filters.highlight
 from nbconvert.transformers.latex import LatexTransformer
+
+# local import
+import exporter
+
 #-----------------------------------------------------------------------------
 # Globals and constants
 #-----------------------------------------------------------------------------
@@ -40,8 +48,17 b' LATEX_JINJA_LOGIC_BLOCK = ["((*", "*))"]'
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
-class LatexExporter(exporter.Exporter):
 
+class LatexExporter(exporter.Exporter):
+    """
+    Exports to a Latex template.  Inherit from this class if your template is
+    LaTeX based and you need custom tranformers/filters.  Inherit from it if 
+    you are writing your own HTML template and need custom tranformers/filters.  
+    If you don't need custom tranformers/filters, just change the 
+    'template_file' config option.  Place your template in the special "/latex" 
+    subfolder of the "../templates" folder.
+    """
+    
     #Extension that the template files use.    
     template_extension = ".tplx"
     
@@ -53,10 +70,10 b' class LatexExporter(exporter.Exporter):'
             'base', config=True,
             help="Name of the template file to use")
     
-    def __init__(self, preprocessors=None, jinja_filters=None, config=None, **kw):
+    def __init__(self, transformers=None, filters=None, config=None, **kw):
         
         #Call base class constructor.
-        super(LatexExporter, self).__init__(preprocessors, jinja_filters, config, **kw)
+        super(LatexExporter, self).__init__(transformers, filters, config, **kw)
         
         self.extract_figure_transformer.display_data_priority = ['latex', 'svg', 'png', 'jpg', 'jpeg' , 'text']
         self.extract_figure_transformer.extra_ext_map={'svg':'pdf'}
@@ -86,9 +103,10 b' class LatexExporter(exporter.Exporter):'
         super(LatexExporter, self)._register_filters()
 
         #Add latex filters to the Jinja2 environment
-        self.register_filter('escape_tex', nbconvert.filters.latex.escape_tex) 
+        self.register_filter('escape_tex', nbconvert.filters.latex.escape_latex) 
         self.register_filter('highlight', nbconvert.filters.highlight.highlight2latex) 
     
+    
     def _register_transformers(self):
         
         #Register the transformers of the base class.

nbconvert/api/markdown.py

@@ -1,4 +1,6 b''
-
+"""
+Exporter that will export your iPynb to Markdown.
+"""
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
@@ -11,15 +13,20 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
 # local import
 import exporter
-from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
-class MarkdownExporter(exporter.Exporter):
 
+class MarkdownExporter(exporter.Exporter):
+    """
+    Exports to a markdown document (.md)
+    """
+    
     file_extension = Unicode(
         'md', config=True, 
         help="Extension of the file that should be written to disk")

nbconvert/api/python.py

@@ -1,6 +1,6 b''
-"""TODO: Docstring
 """
-
+Python exporter which exports Notebook code into a PY file.
+"""
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
@@ -13,15 +13,20 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
 # local import
 import exporter
-from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
-class PythonExporter(exporter.Exporter):
 
+class PythonExporter(exporter.Exporter):
+    """
+    Exports a Python code file.
+    """
+    
     file_extension = Unicode(
         'py', config=True, 
         help="Extension of the file that should be written to disk")
@@ -30,10 +35,10 b' class PythonExporter(exporter.Exporter):'
             'python', config=True,
             help="Name of the template file to use")
 
-    def __init__(self, preprocessors=None, jinja_filters=None, config=None, armor=False, **kw):
+    def __init__(self, transformers=None, filters=None, config=None, armor=False, **kw):
         
         #Call base class constructor.
-        super(PythonExporter, self).__init__(preprocessors, jinja_filters, config, **kw)
+        super(PythonExporter, self).__init__(transformers, filters, config, **kw)
 
         #Set defaults
         self.extract_figure_transformer.enabled = False

nbconvert/api/python_armor.py

@@ -1,4 +1,5 b''
-"""TODO: Docstring
+"""
+Exporter that exports a Python-Armor code file (.py)
 """
 
 #-----------------------------------------------------------------------------
@@ -13,14 +14,19 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
 # local import
 import python.PythonExporter
-from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
+
 class PythonArmorExporter(python.PythonExporter):
+    """
+    Exports a Python-Armor code file (.py)
+    """
 
     template_file = Unicode(
             'python_armor', config=True,

nbconvert/api/reveal.py

@@ -1,6 +1,6 b''
-"""TODO: Docstring
 """
-
+Reveal slide show exporter.
+"""
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
@@ -13,16 +13,22 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
 # local import
-import html
+import basichtml
+
 import nbconvert.transformers.revealhelp
-from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
-class RevealExporter(html.HtmlExporter):
 
+class RevealExporter(basichtml.BasicHtmlExporter):
+    """
+    Exports a Reveal slide show (.HTML) which may be rendered in a web browser.
+    """
+    
     file_extension = Unicode(
         'reveal.html', config=True, 
         help="Extension of the file that should be written to disk")

nbconvert/api/rst.py

@@ -1,6 +1,6 b''
-"""TODO: Docstring
 """
-
+Exporter for exporting notebooks to restructured text.
+"""
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
@@ -13,15 +13,20 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
 # local import
 import exporter
-from IPython.utils.traitlets import Unicode
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
-class RstExporter(exporter.Exporter):
 
+class RstExporter(exporter.Exporter):
+    """
+    Exports restructured text documents.
+    """
+    
     file_extension = Unicode(
         'rst', config=True, 
         help="Extension of the file that should be written to disk")

nbconvert/api/sphinx_howto.py

@@ -1,4 +1,7 b''
-
+"""
+Exporter for exporting notebooks to Sphinx 'HowTo' style latex.  Latex 
+formatted for use with PDFLatex.
+"""
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
@@ -11,15 +14,23 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
 # local import
 import latex
-from IPython.utils.traitlets import Unicode
+
 from nbconvert.transformers.sphinx import SphinxTransformer
+
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
-class SphinxHowtoExporter(latex.LatexExporter):
 
+class SphinxHowtoExporter(latex.LatexExporter):
+    """
+    Exports Sphinx "HowTo" LaTeX documents.  The Sphinx "HowTo" exporter 
+    produces short document format latex for use with PDFLatex.
+    """
+    
     template_file = Unicode(
             'sphinx_howto', config=True,
             help="Name of the template file to use")

nbconvert/api/sphinx_manual.py

@@ -1,4 +1,7 b''
-
+"""
+Exporter for exporting notebooks to Sphinx 'Manual' style latex.  Latex 
+formatted for use with PDFLatex.
+"""
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
@@ -11,14 +14,21 b''
 # Imports
 #-----------------------------------------------------------------------------
 
+from IPython.utils.traitlets import Unicode
+
 # local import
 import sphinx_howto.SphinxHowtoExporter
-from IPython.utils.traitlets import Unicode
+
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
-class SphinxManualExporter(sphinx_howto.SphinxHowtoExporter):
 
+class SphinxManualExporter(sphinx_howto.SphinxHowtoExporter):
+    """
+    Exports Sphinx "Manual" LaTeX documents.  The Sphinx "Manual" exporter 
+    produces book like latex output for use with PDFLatex. 
+    """
+    
     template_file = Unicode(
             'sphinx_manual', config=True,
             help="Name of the template file to use")