Introduce standard structure from coding guidelines in converters/.

converters/__init__.py

@@ -1,3 +1,18 b''
+"""Notebook formatting converters.
+
+This module provides several classes meant to deal with the conversion of
+IPython notebooks to a variety of exported formats. All of these classes
+inherit from `Converter`, which provides some general-purpose functionality
+and defines the API relied upon by the `nbconvert` tool.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, 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.
+#-----------------------------------------------------------------------------
+
 from .html import ConverterHTML
 from .markdown import ConverterMarkdown
 from .bloggerhtml import ConverterBloggerHTML

converters/base.py

@@ -1,7 +1,23 b''
+"""Base classes for the notebook conversion pipeline.
+
+This module defines Converter, from which all objects designed to implement
+a conversion of IPython notebooks to some other format should inherit.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, 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
-from converters.utils import remove_fake_files_url
 
-# Stdlib
+# Stdlib imports
 import codecs
 import io
 import logging
@@ -10,10 +26,16 b' import pprint'
 import re
 from types import FunctionType
 
-# From IPython
+# IPython imports
 from IPython.nbformat import current as nbformat
 
-# local
+# Our own imports
+from converters.utils import remove_fake_files_url
+
+
+#-----------------------------------------------------------------------------
+# Local utilities
+#-----------------------------------------------------------------------------
 
 def clean_filename(filename):
     """
@@ -33,11 +55,11 b' def clean_filename(filename):'
     filename = re.sub(r'[^a-zA-Z0-9_]', '_', filename)
     return filename
 
+
 #-----------------------------------------------------------------------------
 # Class declarations
 #-----------------------------------------------------------------------------
 
-
 class ConversionException(Exception):
     pass
 

converters/bloggerhtml.py

@@ -1,6 +1,31 b''
-from converters.html import ConverterHTML
+"""Notebook export in Blogger-aware HTML.
+
+This file contains `ConverterBloggerHTML`, a subclass of `ConverterHTML` that
+provides output suitable for easy pasting into a blog hosted on the Blogger
+platform. See the class docstring for more information.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib imports
 import io
 
+# Our own imports
+from converters.html import ConverterHTML
+
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
 
 class ConverterBloggerHTML(ConverterHTML):
     """Convert a notebook to html suitable for easy pasting into Blogger.

converters/html.py

@@ -1,15 +1,42 b''
+"""Implements conversion to ordinary HTML output.
+
+This file implements a class that handles rendering IPython notebooks as
+HTML, suitable for posting to the web.
+
+Converters for more specific HTML generation needs (suitable for posting to
+a particular web service) can usefully subclass `ConverterHTML` and override
+certain methods. For output tuned to the Blogger blogging platform, see the
+`ConverterBloggerHTML` class.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, 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.
+#-----------------------------------------------------------------------------
+
 from __future__ import absolute_import
 
+# Stdlib imports
+import io
+import os
+
+# Third-party imports
+from markdown import markdown
+
+# IPython imports
+from IPython.utils import path
+
+# Our own imports
 from converters.base import Converter
 from converters.utils import text_cell, output_container
 from converters.utils import highlight, coalesce_streams, ansi2html
 
-from IPython.utils import path
-from markdown import markdown
-import os
-import io
-
 
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
 class ConverterHTML(Converter):
     extension = 'html'
     blank_symbol = ' '

converters/latex.py

@@ -1,9 +1,35 b''
-from converters.base import Converter
-from converters.utils import markdown2latex, remove_ansi
+"""Notebook export to LaTeX.
+
+This file implements a converter class for rendering IPython notebooks as
+LaTeX, suitable for rendering by pdflatex.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib imports
 import os
 import subprocess
 import sys
 
+# Our own imports
+from converters.base import Converter
+from converters.utils import markdown2latex, remove_ansi
+
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+# XXX: This is a hack that needs to be addressed in a more principled fashion.
 inkscape = 'inkscape'
 if sys.platform == 'darwin':
     inkscape = '/Applications/Inkscape.app/Contents/Resources/bin/inkscape'
@@ -11,6 +37,10 b" if sys.platform == 'darwin':"
         inkscape = None
 
 
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
 class ConverterLaTeX(Converter):
     """Converts a notebook to a .tex file suitable for pdflatex.
 

converters/lexers.py

@@ -1,7 +1,21 b''
+"""A custom pygments lexer for IPython code cells.
+
+Informs The pygments highlighting library of the quirks of IPython's superset
+of Python -- magic commands, !shell commands, etc.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, 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
 #-----------------------------------------------------------------------------
 
+# Third-party imports
 from pygments.lexers import PythonLexer, BashLexer
 from pygments.lexer import bygroups, using
 from pygments.token import Keyword, Operator, Text

converters/markdown.py

@@ -1,8 +1,29 b''
+"""Converter implementing Markdown export.
+
+Implements a Converter that allows IPython notebooks to reasonably rendered
+as a Markdown document.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, 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
+#-----------------------------------------------------------------------------
+
+# Our own imports
 from converters.base import Converter
 from converters.utils import highlight, remove_ansi
 from IPython.utils.text import indent
 
 
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
 class ConverterMarkdown(Converter):
     extension = 'md'
 

converters/notebook.py

@@ -1,10 +1,34 b''
+"""Base class for doing notebook-to-notebook transformations.
+
+This implements a converter class that turns an IPython notebook into another
+IPython notebook, mainly so that it can be subclassed to perform more useful
+and sophisticated transformations.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2011, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib imports
+import json
 import os
+from shutil import rmtree
+
+# Our own imports
 from converters.base import Converter
 from converters.utils import cell_to_lines
-from shutil import rmtree
-import json
 
 
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
 class ConverterNotebook(Converter):
     """
     A converter that is essentially a null-op.

converters/python.py

@@ -1,8 +1,32 b''
-from converters.base import Converter
+"""Notebook export to .py source code files.
+
+Since Python export is provided in the notebook itself (provided by classes
+in `IPython.nbformat`), this class serves mainly as a base class for other
+converters that may wish to implement cell-type-specific behaviors.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, 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
+#-----------------------------------------------------------------------------
+
+# IPython imports
 from IPython.utils.text import indent
+
+# Our own imports
+from converters.base import Converter
 from converters.utils import remove_ansi
 
 
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
 class ConverterPy(Converter):
     """
     A converter that takes a notebook and converts it to a .py file.

converters/rst.py

@@ -1,8 +1,31 b''
+"""Notebook export to reStructuredText (rST).
+
+This file provides a converter class for rendering IPython notebooks as valid
+reStructuredText, suitable for inclusion in e.g. Sphinx documentation.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, 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
+#-----------------------------------------------------------------------------
+
+# IPython imports
+from IPython.utils.text import indent
+
+# Our own imports
 from converters.base import Converter
 from converters.utils import markdown2rst, rst_directive, remove_ansi
-from IPython.utils.text import indent
 
 
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
 class ConverterRST(Converter):
     extension = 'rst'
     heading_level = {1: '=', 2: '-', 3: '`', 4: '\'', 5: '.', 6: '~'}

converters/utils.py

@@ -1,6 +1,24 b''
+"""A one-line description.
+
+A longer description that spans multiple lines.  Explain the purpose of the
+file and provide a short list of the key classes/functions it contains.  This
+is the docstring shown when some does 'import foo;foo?' in IPython, so it
+should be reasonably useful and informative.
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2012, 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
-from lexers import IPythonLexer
 
+# Stdlib imports
 import subprocess
 import copy
 import json
@@ -8,10 +26,19 b' import re'
 import os
 import sys
 
+# IPython imports
 from IPython.utils.text import indent
 from IPython.utils import py3compat
 from IPython.nbformat.v3.nbjson import BytesEncoder
 
+# Our own imports
+from lexers import IPythonLexer
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+_multiline_outputs = ['text', 'html', 'svg', 'latex', 'javascript', 'json']
+
 
 #-----------------------------------------------------------------------------
 # Utility functions
@@ -308,9 +335,6 b' def writes_cell(cell, **kwargs):'
     return py3compat.str_to_unicode(json.dumps(cell, **kwargs), 'utf-8')
 
 
-_multiline_outputs = ['text', 'html', 'svg', 'latex', 'javascript', 'json']
-
-
 def split_lines_cell(cell):
     """
     Split lines within a cell as in