Cleanup and refactor of filters

nbconvert/filters/ansi.py

@@ -1,10 +1,46 b''
+"""Filters for processing ANSI colors within Jinja templates.
+"""
+#-----------------------------------------------------------------------------
+# 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 re
 
-def remove_ansi(src):
-    return re.sub(r'\033\[(0|\d;\d\d)m', '', src)
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
 
+def remove_ansi(source):
+    """
+    Remove ansi from text
+    
+    Parameters
+    ----------
+    source : str
+        Source to remove the ansi from
+    """
+    
+    return re.sub(r'\033\[(0|\d;\d\d)m', '', source)
 
-def ansi2html(txt):
+
+def ansi2html(text):
+    """
+    Conver ansi colors to html colors.
+    
+    Parameters
+    ----------
+    text : str
+        Text containing ansi colors to convert to html
+    """
+    
     ansi_colormap = {
         '30': 'ansiblack',
         '31': 'ansired',
@@ -18,7 +54,7 b' def ansi2html(txt):'
     }
 
     # do ampersand first
-    txt = txt.replace('&', '&')
+    text = text.replace('&', '&')
     html_escapes = {
         '<': '&lt;',
         '>': '&gt;',
@@ -28,10 +64,10 b' def ansi2html(txt):'
     }
     
     for c, escape in html_escapes.iteritems():
-        txt = txt.replace(c, escape)
+        text = text.replace(c, escape)
 
     ansi_re = re.compile('\x1b' + r'\[([\dA-Fa-f;]*?)m')
-    m = ansi_re.search(txt)
+    m = ansi_re.search(text)
     opened = False
     cmds = []
     opener = ''
@@ -52,10 +88,10 b' def ansi2html(txt):'
             opener = '<span class="%s">' % (' '.join(classes))
         else:
             opener = ''
-        txt = re.sub(ansi_re, closer + opener, txt, 1)
+        text = re.sub(ansi_re, closer + opener, text, 1)
 
-        m = ansi_re.search(txt)
+        m = ansi_re.search(text)
 
     if opened:
-        txt += '</span>'
-    return txt
  No newline at end of file
+        text += '</span>'
+    return text

nbconvert/filters/highlight.py

@@ -1,3 +1,18 b''
+"""
+Module containing filter functions that allow code to be highlighted
+from within Jinja templates.
+"""
+#-----------------------------------------------------------------------------
+# 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  pygments import highlight as pygements_highlight
 from pygments.lexers import get_lexer_by_name
@@ -10,32 +25,58 b' from nbconvert.utils.lexers import IPythonLexer'
 #-----------------------------------------------------------------------------
 # Globals and constants
 #-----------------------------------------------------------------------------
-_multiline_outputs = ['text', 'html', 'svg', 'latex', 'javascript', 'json']
 
+MULTILINE_OUTPUTS = ['text', 'html', 'svg', 'latex', 'javascript', 'json']
 
 #-----------------------------------------------------------------------------
 # Utility functions
 #-----------------------------------------------------------------------------
-def highlight(src, lang='ipython'):
+
+def highlight(source, language='ipython'):
     """
     Return a syntax-highlighted version of the input source as html output.
+    
+    Parameters
+    ----------
+    source : str
+        Source code to highlight the syntax of.
+    language : str
+        Language to highlight the syntax of.
     """
     
-    return _pygment_highlight(src, HtmlFormatter(), lang)
+    return _pygment_highlight(source, HtmlFormatter(), language)
+
 
-def highlight2latex(src, lang='ipython'):
+def highlight2latex(source, language='ipython'):
     """
     Return a syntax-highlighted version of the input source as latex output.
+    
+    Parameters
+    ----------
+    source : str
+        Source code to highlight the syntax of.
+    language : str
+        Language to highlight the syntax of.
     """
-    return _pygment_highlight(src, LatexFormatter(), lang)
+    return _pygment_highlight(source, LatexFormatter(), language)
 
-def _pygment_highlight(src, output_formatter, lang='ipython'):
+
+def _pygment_highlight(source, output_formatter, language='ipython'):
     """
     Return a syntax-highlighted version of the input source
+    
+    Parameters
+    ----------
+    source : str
+        Source code to highlight the syntax of.
+    output_formatter : Pygments formatter
+    language : str
+        Language to highlight the syntax of.
     """
-    if lang == 'ipython':
+    
+    if language == 'ipython':
         lexer = IPythonLexer()
     else:
-        lexer = get_lexer_by_name(lang, stripall=True)
+        lexer = get_lexer_by_name(language, stripall=True)
 
-    return pygements_highlight(src, lexer, output_formatter) 
+    return pygements_highlight(source, lexer, output_formatter) 

nbconvert/filters/latex.py

@@ -1,7 +1,6 b''
-"""Latex transformer.
+"""Latex filters.
 
-Module that allows latex output notebooks to be conditioned before
-they are converted.
+Module of useful filters for processing Latex within Jinja latex templates.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
@@ -33,16 +32,32 b' LATEX_SUBS = ('
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
-def escape_tex(value):
-    newval = value
+
+def escape_latex(text):
+    """
+    Escape characters that may conflict with latex.
+    
+    Parameters
+    ----------
+    text : str
+        Text containing characters that may conflict with Latex
+    """
+    return_text = text
     for pattern, replacement in LATEX_SUBS:
-        newval = pattern.sub(replacement, newval)
-    return newval
+        return_text = pattern.sub(replacement, return_text)
+    return return_text
     
     
 def rm_math_space(text):
     """
     Remove the space between latex math commands and enclosing $ symbols.
+    This filter is important because latex isn't as flexible as the notebook
+    front end when it comes to flagging math using ampersand symbols.
+    
+    Parameters
+    ----------
+    text : str
+        Text to filter.
     """
 
     # First, scan through the markdown looking for $.  If

nbconvert/filters/markdown.py

@@ -1,7 +1,6 b''
-"""Markdown utilities
-
-This file contains a collection of utility functions for dealing with 
-markdown.
+"""Markdown filters
+This file contains a collection of utility filters for dealing with 
+markdown within Jinja templates.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
@@ -24,17 +23,15 b' import subprocess'
 # Functions
 #-----------------------------------------------------------------------------
 
-# Pandoc-dependent code
-def markdown2latex(src):
+def markdown2latex(source):
     """Convert a markdown string to LaTeX via pandoc.
 
     This function will raise an error if pandoc is not installed.
-
     Any error messages generated by pandoc are printed to stderr.
 
     Parameters
     ----------
-    src : string
+    source : string
       Input string, assumed to be valid markdown.
 
     Returns
@@ -44,23 +41,25 b' def markdown2latex(src):'
     """
     p = subprocess.Popen('pandoc -f markdown -t latex'.split(),
                          stdin=subprocess.PIPE, stdout=subprocess.PIPE)
-    out, err = p.communicate(src.encode('utf-8'))
+    
+    out, err = p.communicate(source.encode('utf-8'))
+    
     if err:
         print(err, file=sys.stderr)
     #print('*'*20+'\n', out, '\n'+'*'*20)  # dbg
+    
     return unicode(out, 'utf-8')
 
 
-def markdown2rst(src):
+def markdown2rst(source):
     """Convert a markdown string to LaTeX via pandoc.
 
     This function will raise an error if pandoc is not installed.
-
     Any error messages generated by pandoc are printed to stderr.
 
     Parameters
     ----------
-    src : string
+    source : string
       Input string, assumed to be valid markdown.
 
     Returns
@@ -70,8 +69,11 b' def markdown2rst(src):'
     """
     p = subprocess.Popen('pandoc -f markdown -t rst'.split(),
                          stdin=subprocess.PIPE, stdout=subprocess.PIPE)
-    out, err = p.communicate(src.encode('utf-8'))
+    
+    out, err = p.communicate(source.encode('utf-8'))
+    
     if err:
         print(err, file=sys.stderr)
     #print('*'*20+'\n', out, '\n'+'*'*20)  # dbg
-    return unicode(out, 'utf-8')
  No newline at end of file
+    
+    return unicode(out, 'utf-8')

nbconvert/filters/strings.py

@@ -1,6 +1,7 b''
-"""String utilities.
+"""String filters.
 
-Contains a collection of useful string manipulations functions.
+Contains a collection of useful string manipulation filters for use in Jinja
+templates.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
@@ -15,43 +16,89 b' Contains a collection of useful string manipulations functions.'
 #-----------------------------------------------------------------------------
 
 # Our own imports
-import textwrap #TODO
+import textwrap
 
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
+
 def wrap(text, width=100):
-    """ Intelligently wrap text"""
+    """ 
+    Intelligently wrap text.
+    Wrap text without breaking words if possible.
+    
+    Parameters
+    ----------
+    text : str
+        Text to wrap.
+    width : int, optional
+        Number of characters to wrap to, default 100.
+    """
 
-    splitt = text.split('\n')
-    wrp = map(lambda x:textwrap.wrap(x,width),splitt)
+    split_text = text.split('\n')
+    wrp = map(lambda x:textwrap.wrap(x,width), split_text)
     wrpd = map('\n'.join, wrp)
     return '\n'.join(wrpd)
 
 
 def strip_dollars(text):
-    """Remove all dollar symbols from text"""
+    """
+    Remove all dollar symbols from text
+    
+    Parameters
+    ----------
+    text : str
+        Text to remove dollars from
+    """
 
     return text.strip('$')
 
 
-#TODO: Comment me.
-def rm_fake(strng):
-    return strng.replace('/files/', '')
+def rm_fake(text):
+    """
+    Remove all occurrences of '/files/' from text
+    
+    Parameters
+    ----------
+    text : str
+        Text to remove '/files/' from
+    """
+    return text.replace('/files/', '')
 
 
-#TODO: Comment me.
-def python_comment(string):
-    return '# '+'\n# '.join(string.split('\n'))
+def python_comment(text):
+    """
+    Build a Python comment line from input text.
+    
+    Parameters
+    ----------
+    text : str
+        Text to comment out.
+    """
+    
+    #Replace line breaks with line breaks and comment symbols.
+    #Also add a comment symbol at the beginning to comment out
+    #the first line.
+    return '# '+'\n# '.join(text.split('\n')) 
+
 
-def get_lines(src, start=None,end=None):
+def get_lines(text, start=None,end=None):
     """
     Split the input text into separate lines and then return the 
     lines that the caller is interested in.
+    
+    Parameters
+    ----------
+    text : str
+        Text to parse lines from.
+    start : int, optional
+        First line to grab from.
+    end : int, optional
+        Last line to grab from.
     """
     
     # Split the input into lines.
-    lines = src.split("\n")
+    lines = text.split("\n")
     
     # Return the right lines.
     return "\n".join(lines[start:end]) #re-join