Docstring decorator

nbconvert.py

@@ -96,7 +96,7 b' class NbConvertApp(Application):'
         ipynb_file = (self.extra_args)[2]
 
         #Export
-        return_value = export_by_name(ipynb_file, export_type)
+        return_value = export_by_name(export_type, ipynb_file)
         if return_value is None:
             print("Error: '%s' template not found." % export_type)
             return

nbconvert/export.py

@@ -15,6 +15,7 b' Module containing single call export functions.'
 
 import sys
 import inspect
+from functools import wraps
 
 from IPython.nbformat.v3.nbbase import NotebookNode
 
@@ -30,17 +31,15 b' from .exporters.rst import RstExporter'
 from .exporters.sphinx_howto import SphinxHowtoExporter
 from .exporters.sphinx_manual import SphinxManualExporter
 
-
 #-----------------------------------------------------------------------------
-# Functions
+# Classes
 #-----------------------------------------------------------------------------
 
-def export(nb, config=None, transformers=None, filters=None, exporter_type=Exporter):
-    """
-    Export a notebook object using specific exporter class.
+def DocDecorator(f):    
     
-    Parameters
-    ----------
+    #Set docstring of function
+    f.__doc__ = f.__doc__ + """
+    nb : Notebook node
     config : config
         User configuration instance.
     transformers : list[of transformer]
@@ -52,12 +51,6 b' def export(nb, config=None, transformers=None, filters=None, exporter_type=Expor'
         Custom filters to make accessible to the Jinja templates.  Any
         filters specified here will override existing filters if a
         naming conflict occurs.
-    exporter_type:
-        Class type of the exporter that should be used.  This method
-        will initialize 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.
         
     Returns
     ----------
@@ -70,7 +63,30 b' def export(nb, config=None, transformers=None, filters=None, exporter_type=Expor'
     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.
+        specifies what extension the output should be saved as."""
+            
+    @wraps(f)
+    def decorator(*args, **kwargs):
+        return f(*args, **kwargs)
+    
+    return decorator
+
+
+#-----------------------------------------------------------------------------
+# Functions
+#-----------------------------------------------------------------------------
+
+@DocDecorator
+def export(exporter_type, nb, config=None, transformers=None, filters=None):
+    """
+    Export a notebook object using specific exporter class.
+    
+    exporter_type : Exporter class type
+        Class type of the exporter that should be used.  This method
+        will initialize 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
@@ -96,382 +112,95 b' def export(nb, config=None, transformers=None, filters=None, exporter_type=Expor'
     return output, resources, exporter_instance
 
 
+@DocDecorator
 def export_sphinx_manual(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Sphinx Manual LaTeX
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, SphinxManualExporter)
+    return export(SphinxManualExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_sphinx_howto(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Sphinx HowTo LaTeX
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, SphinxHowtoExporter)
+    return export(SphinxHowtoExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_basic_html(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Basic HTML
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, BasicHtmlExporter)
+    return export(BasicHtmlExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_full_html(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Full HTML
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, FullHtmlExporter)
+    return export(FullHtmlExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_latex(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to LaTeX
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, LatexExporter)
+    return export(LatexExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_markdown(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Markdown
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, MarkdownExporter)
+    return export(MarkdownExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_python(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Python
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, PythonExporter)
+    return export(PythonExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_python_armor(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Python (Armor)
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, PythonArmorExporter)
+    return export(PythonArmorExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_reveal(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to Reveal
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, RevealExporter)
+    return export(RevealExporter, nb, config, transformers, filters)
 
 
+@DocDecorator
 def export_rst(nb, config=None, transformers=None, filters=None):
     """
     Export a notebook object to RST
-    
-    Parameters
-    ----------
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    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.
     """
-    return export(nb, config, transformers, filters, RstExporter)
+    return export(RstExporter, nb, config, transformers, filters)
 
 
-def export_by_name(nb, template_name, config=None, transformers=None, filters=None):
+@DocDecorator
+def export_by_name(template_name, nb, config=None, transformers=None, filters=None):
     """
     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.
     
-    Parameters
-    ----------
     template_name : str
         Name of the template style to export to.
-    config : config
-        User configuration instance.
-    transformers : list[of transformer]
-        Custom transformers to apply to the notebook prior to engaging
-        the Jinja template engine.  Any transformers specified here 
-        will override existing transformers if a naming conflict
-        occurs.
-    filters : list[of filter]
-        Custom filters to make accessible to the Jinja templates.  Any
-        filters specified here will override existing filters if a
-        naming conflict occurs.
-        
-    Returns
-    ----------
-    tuple- (output, resources, exporter_instance)
-    None- if template not found
-    
-    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.
     """
     
     function_name = "export_" + template_name.lower()