Adding citation support.

IPython/nbconvert/filters/citation.py

@@ -0,0 +1,70 b''
+"""Citation handling for LaTeX output."""
+
+#-----------------------------------------------------------------------------
+# 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.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+
+__all__ = ['parse_citation']
+
+
+def parse_citation(s):
+    """Parse citations in Markdown cells.
+    
+    This looks for HTML tags having a data attribute names `data-cite`
+    and replaces it by the call to LaTeX cite command. The tranformation
+    looks like this:
+    
+    `<cite data-cite="granger">(Granger, 2013)</cite>`
+    
+    Becomes
+    
+    `\\cite{granger}`
+    
+    Any HTML tag can be used, which allows the citations to be formatted
+    in HTML in any manner.
+    """
+    try:
+        from lxml import html
+    except ImportError:
+        return s
+
+    tree = html.fragment_fromstring(s, create_parent='div')
+    _process_node_cite(tree)
+    s = html.tostring(tree)
+    s = s.lstrip('<div>')
+    s = s.rstrip('</div>')
+    return s
+
+
+def _process_node_cite(node):
+    """Do the citation replacement as we walk the lxml tree."""
+    
+    def _get(o, name):
+        value = getattr(o, name)
+        return '' if value is None else value
+    
+    if 'data-cite' in node.attrib:
+        cite = '\cite{%(ref)s}' % {'ref': node.attrib['data-cite']}
+        prev = node.getprevious()
+        if prev is not None:
+            prev.tail = _get(prev, 'tail') + cite + _get(node, 'tail')
+        else:
+            parent = node.getparent()
+            if parent is not None:
+                parent.text = _get(parent, 'text') + cite + _get(node, 'tail')
+        try:
+            node.getparent().remove(node)
+        except AttributeError:
+            pass
+    else:
+        for child in node:
+            _process_node_cite(child)

IPython/nbconvert/filters/tests/test_citation.py

@@ -0,0 +1,54 b''
+#-----------------------------------------------------------------------------
+# 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 ..citation import parse_citation
+
+#-----------------------------------------------------------------------------
+# Tests
+#-----------------------------------------------------------------------------
+
+test_md = """
+# My Heading
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus ac magna non augue
+porttitor scelerisque ac id diam <cite data-cite="granger">Granger</cite>. Mauris elit
+velit, lobortis sed interdum at, vestibulum vitae libero <strong data-cite="fperez">Perez</strong>.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit
+<em data-cite="takluyver">Thomas</em>. Quisque iaculis ligula ut ipsum mattis viverra.
+
+* One <cite data-cite="jdfreder">Jonathan</cite>.
+* Two <cite data-cite="carreau">Matthias</cite>.
+* Three <cite data-cite="ivanov">Paul</cite>.
+"""
+
+test_md_parsed = """
+# My Heading
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus ac magna non augue
+porttitor scelerisque ac id diam \cite{granger}. Mauris elit
+velit, lobortis sed interdum at, vestibulum vitae libero \cite{fperez}.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit
+\cite{takluyver}. Quisque iaculis ligula ut ipsum mattis viverra.
+
+* One \cite{jdfreder}.
+* Two \cite{carreau}.
+* Three \cite{ivanov}.
+"""
+
+def test_parse_citation():
+    """Are citations parsed properly?"""
+    try:
+        import lxml
+    except ImportError:
+        assert test_md == parse_citation(test_md) 
+    else:
+        assert test_md_parsed == parse_citation(test_md)

IPython/nbconvert/exporters/exporter.py

@@ -1,518 +1,519 b''
 """This module defines Exporter, a highly configurable converter
 that uses Jinja2 to export notebook files into different formats.
 """
 
 #-----------------------------------------------------------------------------
 # 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
 import io
 import os
 import inspect
 import copy
 import collections
 import datetime
 
 # other libs/dependencies
 from jinja2 import Environment, FileSystemLoader, ChoiceLoader, TemplateNotFound
 
 # IPython imports
 from IPython.config.configurable import LoggingConfigurable
 from IPython.config import Config
 from IPython.nbformat import current as nbformat
 from IPython.utils.traitlets import MetaHasTraits, DottedObjectName, Unicode, List, Dict, Any
 from IPython.utils.importstring import import_item
 from IPython.utils.text import indent
 from IPython.utils import py3compat
 
 from IPython.nbconvert import preprocessors as nbpreprocessors
 from IPython.nbconvert import filters
 
 #-----------------------------------------------------------------------------
 # Globals and constants
 #-----------------------------------------------------------------------------
 
 #Jinja2 extensions to load.
 JINJA_EXTENSIONS = ['jinja2.ext.loopcontrols']
 
 default_filters = {
         'indent': indent,
         'markdown2html': filters.markdown2html,
         'ansi2html': filters.ansi2html,
         'filter_data_type': filters.DataTypeFilter,
         'get_lines': filters.get_lines,
         'highlight2html': filters.highlight2html,
         'highlight2latex': filters.highlight2latex,
         'ipython2python': filters.ipython2python,
         'posix_path': filters.posix_path,
         'markdown2latex': filters.markdown2latex,
         'markdown2rst': filters.markdown2rst,
         'comment_lines': filters.comment_lines,
         'strip_ansi': filters.strip_ansi,
         'strip_dollars': filters.strip_dollars,
         'strip_files_prefix': filters.strip_files_prefix,
         'html2text' : filters.html2text,
         'add_anchor': filters.add_anchor,
         'ansi2latex': filters.ansi2latex,
         'strip_math_space': filters.strip_math_space,
         'wrap_text': filters.wrap_text,
         'escape_latex': filters.escape_latex,
+        'parse_citation': filters.parse_citation
 }
 
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
 
 class ResourcesDict(collections.defaultdict):
     def __missing__(self, key):
         return ''
 
 
 class Exporter(LoggingConfigurable):
     """
     Exports notebooks into other file formats.  Uses Jinja 2 templating engine
     to output new formats.  Inherit from this class if you are creating a new
     template type along with new filters/preprocessors.  If the filters/
     preprocessors provided by default suffice, there is no need to inherit from
     this class.  Instead, override the template_file and file_extension
     traits via a config file.
 
     {filters}
     """
     
     # finish the docstring
     __doc__ = __doc__.format(filters = '- '+'\n    - '.join(default_filters.keys()))
 
 
     template_file = Unicode(u'default',
             config=True,
             help="Name of the template file to use")
     def _template_file_changed(self, name, old, new):
         if new=='default':
             self.template_file = self.default_template
         else:
             self.template_file = new
         self.template = None
         self._load_template()
     
     default_template = Unicode(u'')
     template = Any()
     environment = Any()
 
     file_extension = Unicode(
         'txt', config=True, 
         help="Extension of the file that should be written to disk"
         )
 
     template_path = List(['.'], config=True)
     def _template_path_changed(self, name, old, new):
         self._load_template()
 
     default_template_path = Unicode(
         os.path.join("..", "templates"), 
         help="Path where the template files are located.")
 
     template_skeleton_path = Unicode(
         os.path.join("..", "templates", "skeleton"), 
         help="Path where the template skeleton files are located.") 
 
     #Jinja block definitions
     jinja_comment_block_start = Unicode("", config=True)
     jinja_comment_block_end = Unicode("", config=True)
     jinja_variable_block_start = Unicode("", config=True)
     jinja_variable_block_end = Unicode("", config=True)
     jinja_logic_block_start = Unicode("", config=True)
     jinja_logic_block_end = Unicode("", config=True)
     
     #Extension that the template files use.    
     template_extension = Unicode(".tpl", config=True)
 
     #Configurability, allows the user to easily add filters and preprocessors.
     preprocessors = List(config=True,
         help="""List of preprocessors, by name or namespace, to enable.""")
 
     filters = Dict(config=True,
         help="""Dictionary of filters, by name and namespace, to add to the Jinja
         environment.""")
 
     default_preprocessors = List([nbpreprocessors.coalesce_streams,
                                  nbpreprocessors.SVG2PDFPreprocessor,
                                  nbpreprocessors.ExtractOutputPreprocessor,
                                  nbpreprocessors.CSSHTMLHeaderPreprocessor,
                                  nbpreprocessors.RevealHelpPreprocessor,
                                  nbpreprocessors.LatexPreprocessor,
                                  nbpreprocessors.SphinxPreprocessor],
         config=True,
         help="""List of preprocessors available by default, by name, namespace, 
         instance, or type.""")
 
 
     def __init__(self, config=None, extra_loaders=None, **kw):
         """
         Public constructor
     
         Parameters
         ----------
         config : config
             User configuration instance.
         extra_loaders : list[of Jinja Loaders]
             ordered list of Jinja loader to find templates. Will be tried in order
             before the default FileSystem ones.
         template : str (optional, kw arg)
             Template to use when exporting.
         """
         if not config:
             config = self.default_config
         
         super(Exporter, self).__init__(config=config, **kw)
 
         #Init
         self._init_template()
         self._init_environment(extra_loaders=extra_loaders)
         self._init_preprocessors()
         self._init_filters()
 
 
     @property
     def default_config(self):
         return Config()
     
     def _config_changed(self, name, old, new):
         """When setting config, make sure to start with our default_config"""
         c = self.default_config
         if new:
             c.merge(new)
         if c != old:
             self.config = c
         super(Exporter, self)._config_changed(name, old, c)
         
 
     def _load_template(self):
         """Load the Jinja template object from the template file
         
         This is a no-op if the template attribute is already defined,
         or the Jinja environment is not setup yet.
         
         This is triggered by various trait changes that would change the template.
         """
         if self.template is not None:
             return
         # called too early, do nothing
         if self.environment is None:
             return
         # Try different template names during conversion.  First try to load the
         # template by name with extension added, then try loading the template
         # as if the name is explicitly specified, then try the name as a 
         # 'flavor', and lastly just try to load the template by module name.
         module_name = self.__module__.rsplit('.', 1)[-1]
         try_names = []
         if self.template_file:
             try_names.extend([
                 self.template_file + self.template_extension,
                 self.template_file,
                 module_name + '_' + self.template_file + self.template_extension,
             ])
         try_names.append(module_name + self.template_extension)
         for try_name in try_names:
             self.log.debug("Attempting to load template %s", try_name)
             try:
                 self.template = self.environment.get_template(try_name)
             except (TemplateNotFound, IOError):
                 pass
             except Exception as e:
                 self.log.warn("Unexpected exception loading template: %s", try_name, exc_info=True)
             else:
                 self.log.info("Loaded template %s", try_name)
                 break
     
     def from_notebook_node(self, nb, resources=None, **kw):
         """
         Convert a notebook from a notebook node instance.
     
         Parameters
         ----------
         nb : Notebook node
         resources : dict (**kw) 
             of additional resources that can be accessed read/write by 
             preprocessors and filters.
         """
         nb_copy = copy.deepcopy(nb)
         resources = self._init_resources(resources)
 
         # Preprocess
         nb_copy, resources = self._preprocess(nb_copy, resources)
 
         self._load_template()
 
         if self.template is not None:
             output = self.template.render(nb=nb_copy, resources=resources)
         else:
             raise IOError('template file "%s" could not be found' % self.template_file)
         return output, resources
 
 
     def from_filename(self, filename, resources=None, **kw):
         """
         Convert a notebook from a notebook file.
     
         Parameters
         ----------
         filename : str
             Full filename of the notebook file to open and convert.
         """
 
         #Pull the metadata from the filesystem.
         if resources is None:
             resources = ResourcesDict()
         if not 'metadata' in resources or resources['metadata'] == '':
             resources['metadata'] = ResourcesDict()
         basename = os.path.basename(filename)
         notebook_name = basename[:basename.rfind('.')]
         resources['metadata']['name'] = notebook_name
 
         modified_date = datetime.datetime.fromtimestamp(os.path.getmtime(filename))
         resources['metadata']['modified_date'] = modified_date.strftime("%B %d, %Y")
         
         with io.open(filename) as f:
             return self.from_notebook_node(nbformat.read(f, 'json'), resources=resources,**kw)
 
 
     def from_file(self, file_stream, resources=None, **kw):
         """
         Convert a notebook from a notebook file.
     
         Parameters
         ----------
         file_stream : file-like object
             Notebook file-like object to convert.
         """
         return self.from_notebook_node(nbformat.read(file_stream, 'json'), resources=resources, **kw)
 
 
     def register_preprocessor(self, preprocessor, enabled=False):
         """
         Register a preprocessor.
         Preprocessors are classes that act upon the notebook before it is
         passed into the Jinja templating engine.  Preprocessors are also
         capable of passing additional information to the Jinja
         templating engine.
     
         Parameters
         ----------
         preprocessor : preprocessor
         """
         if preprocessor is None:
             raise TypeError('preprocessor')
         isclass = isinstance(preprocessor, type)
         constructed = not isclass
 
         #Handle preprocessor's registration based on it's type
         if constructed and isinstance(preprocessor, py3compat.string_types):
             #Preprocessor is a string, import the namespace and recursively call
             #this register_preprocessor method
             preprocessor_cls = import_item(preprocessor)
             return self.register_preprocessor(preprocessor_cls, enabled)
         
         if constructed and hasattr(preprocessor, '__call__'):
             #Preprocessor is a function, no need to construct it.
             #Register and return the preprocessor.
             if enabled:
                 preprocessor.enabled = True
             self._preprocessors.append(preprocessor)
             return preprocessor
 
         elif isclass and isinstance(preprocessor, MetaHasTraits):
             #Preprocessor is configurable.  Make sure to pass in new default for 
             #the enabled flag if one was specified.
             self.register_preprocessor(preprocessor(parent=self), enabled)
 
         elif isclass:
             #Preprocessor is not configurable, construct it
             self.register_preprocessor(preprocessor(), enabled)
 
         else:
             #Preprocessor is an instance of something without a __call__ 
             #attribute.  
             raise TypeError('preprocessor')
 
 
     def register_filter(self, name, jinja_filter):
         """
         Register a filter.
         A filter is a function that accepts and acts on one string.  
         The filters are accesible within the Jinja templating engine.
     
         Parameters
         ----------
         name : str
             name to give the filter in the Jinja engine
         filter : filter
         """
         if jinja_filter is None:
             raise TypeError('filter')
         isclass = isinstance(jinja_filter, type)
         constructed = not isclass
 
         #Handle filter's registration based on it's type
         if constructed and isinstance(jinja_filter, py3compat.string_types):
             #filter is a string, import the namespace and recursively call
             #this register_filter method
             filter_cls = import_item(jinja_filter)
             return self.register_filter(name, filter_cls)
         
         if constructed and hasattr(jinja_filter, '__call__'):
             #filter is a function, no need to construct it.
             self.environment.filters[name] = jinja_filter
             return jinja_filter
 
         elif isclass and isinstance(jinja_filter, MetaHasTraits):
             #filter is configurable.  Make sure to pass in new default for 
             #the enabled flag if one was specified.
             filter_instance = jinja_filter(parent=self)
             self.register_filter(name, filter_instance )
 
         elif isclass:
             #filter is not configurable, construct it
             filter_instance = jinja_filter()
             self.register_filter(name, filter_instance)
 
         else:
             #filter is an instance of something without a __call__ 
             #attribute.  
             raise TypeError('filter')
 
         
     def _init_template(self):
         """
         Make sure a template name is specified.  If one isn't specified, try to
         build one from the information we know.
         """
         self._template_file_changed('template_file', self.template_file, self.template_file)
         
 
     def _init_environment(self, extra_loaders=None):
         """
         Create the Jinja templating environment.
         """
         here = os.path.dirname(os.path.realpath(__file__))
         loaders = []
         if extra_loaders:
             loaders.extend(extra_loaders)
 
         paths = self.template_path
         paths.extend([os.path.join(here, self.default_template_path),
                       os.path.join(here, self.template_skeleton_path)])
         loaders.append(FileSystemLoader(paths))
 
         self.environment = Environment(
             loader= ChoiceLoader(loaders),
             extensions=JINJA_EXTENSIONS
             )
         
         #Set special Jinja2 syntax that will not conflict with latex.
         if self.jinja_logic_block_start:
             self.environment.block_start_string = self.jinja_logic_block_start
         if self.jinja_logic_block_end:
             self.environment.block_end_string = self.jinja_logic_block_end
         if self.jinja_variable_block_start:
             self.environment.variable_start_string = self.jinja_variable_block_start
         if self.jinja_variable_block_end:
             self.environment.variable_end_string = self.jinja_variable_block_end
         if self.jinja_comment_block_start:
             self.environment.comment_start_string = self.jinja_comment_block_start
         if self.jinja_comment_block_end:
             self.environment.comment_end_string = self.jinja_comment_block_end
 
     
     def _init_preprocessors(self):
         """
         Register all of the preprocessors needed for this exporter, disabled
         unless specified explicitly.
         """
         self._preprocessors = []
 
         #Load default preprocessors (not necessarly enabled by default).
         if self.default_preprocessors:
             for preprocessor in self.default_preprocessors:
                 self.register_preprocessor(preprocessor)
 
         #Load user preprocessors.  Enable by default.
         if self.preprocessors:
             for preprocessor in self.preprocessors:
                 self.register_preprocessor(preprocessor, enabled=True)
  
 
     def _init_filters(self):
         """
         Register all of the filters required for the exporter.
         """
         
         #Add default filters to the Jinja2 environment
         for key, value in default_filters.items():
             self.register_filter(key, value)
 
         #Load user filters.  Overwrite existing filters if need be.
         if self.filters:
             for key, user_filter in self.filters.items():
                 self.register_filter(key, user_filter)
 
 
     def _init_resources(self, resources):
 
         #Make sure the resources dict is of ResourcesDict type.
         if resources is None:
             resources = ResourcesDict()
         if not isinstance(resources, ResourcesDict):
             new_resources = ResourcesDict()
             new_resources.update(resources)
             resources = new_resources 
 
         #Make sure the metadata extension exists in resources
         if 'metadata' in resources:
             if not isinstance(resources['metadata'], ResourcesDict):
                 resources['metadata'] = ResourcesDict(resources['metadata'])
         else:
             resources['metadata'] = ResourcesDict()
             if not resources['metadata']['name']: 
                 resources['metadata']['name'] = 'Notebook'
 
         #Set the output extension
         resources['output_extension'] = self.file_extension
         return resources
         
 
     def _preprocess(self, nb, resources):
         """
         Preprocess the notebook before passing it into the Jinja engine.
         To preprocess the notebook is to apply all of the 
     
         Parameters
         ----------
         nb : notebook node
             notebook that is being exported.
         resources : a dict of additional resources that
             can be accessed read/write by preprocessors
             and filters.
         """
         
         # Do a copy.deepcopy first, 
         # we are never safe enough with what the preprocessors could do.
         nbc =  copy.deepcopy(nb)
         resc = copy.deepcopy(resources)
 
         #Run each preprocessor on the notebook.  Carry the output along
         #to each preprocessor
         for preprocessor in self._preprocessors:
             nbc, resc = preprocessor(nbc, resc)
         return nbc, resc

IPython/nbconvert/filters/__init__.py

@@ -1,6 +1,7 b''
 from .ansi import *
 from .datatypefilter import *
 from .highlight import *
 from .latex import *
 from .markdown import *
 from .strings import *
+from .citation import *
  No newline at end of file

IPython/nbconvert/templates/latex/latex_basic.tplx

@@ -1,270 +1,274 b''
 ((*- extends 'display_priority.tplx' -*))
 
 
 \nonstopmode
 
 ((* block in_prompt *))
 ((* endblock in_prompt *))
 
 ((* block output_prompt *))
 ((* endblock output_prompt *))
 
 ((* block codecell *))
 \begin{codecell}
 ((( super() )))
 \end{codecell}
 ((* endblock *))
 
 ((* block input *))
 \begin{codeinput}
 \begin{lstlisting}
 ((( cell.input )))
 \end{lstlisting}
 \end{codeinput}
 ((* endblock input *))
 
 ((= Those Two are for error displaying
 even if the first one seem to do nothing, 
 it introduces a new line
 =))
 
 ((* block pyerr *))
 \begin{traceback}
 \begin{verbatim}
 ((( super() )))
 \end{verbatim}
 \end{traceback}
 ((* endblock pyerr *))
 
 ((* block traceback_line *))
 ((( line | indent | strip_ansi )))
 ((* endblock traceback_line *))
 ((= .... =))
 
 ((*- block output_group -*))
 \begin{codeoutput}
 ((( super() )))
 \end{codeoutput}
 ((* endblock *))
 
 ((*- block data_png -*))
 \begin{center}
 \includegraphics[max size={0.7\textwidth}{0.9\textheight}]{((( output.png_filename | posix_path )))}
 \par
 \end{center}
 ((*- endblock -*))
 
 ((*- block data_jpg -*))
 \begin{center}
 \includegraphics[max size={0.7\textwidth}{0.9\textheight}]{((( output.jpeg_filename | posix_path )))}
 \par
 \end{center}
 ((*- endblock -*))
 
 ((*- block data_svg -*))
 \begin{center}
 \includegraphics[width=0.7\textwidth]{((( output.svg_filename | posix_path )))}
 \par
 \end{center}
 ((*- endblock -*))
 
 ((*- block data_pdf -*))
 \begin{center}
 \includegraphics[width=0.7\textwidth]{((( output.pdf_filename | posix_path )))}
 \par
 \end{center}
 ((*- endblock -*))
 
 ((* block pyout *))
 ((* block data_priority scoped *))
 ((( super() )))
 ((* endblock *))
 ((* endblock pyout *))
 
 ((* block data_text *))
 \begin{verbatim}
 ((( output.text )))
 \end{verbatim}
 ((* endblock *))
 
 ((* block data_latex -*))
 ((*- if output.latex.startswith('$'): -*)) \begin{equation*}
     ((( output.latex | strip_dollars )))
     \end{equation*}
 ((*- else -*))
     ((( output.latex )))
 ((*- endif *))
 ((* endblock *))
 
 ((* block stream *))
 \begin{Verbatim}[commandchars=\\\{\}]
 ((( output.text | ansi2latex )))
 \end{Verbatim}
 ((* endblock stream *))
 
 ((* block markdowncell scoped *))
-((( cell.source | markdown2latex )))
+((( cell.source | parse_citation | markdown2latex )))
 ((* endblock markdowncell *))
 
 ((* block headingcell scoped -*))
-((( ('#' * cell.level + cell.source) | replace('\n', ' ') | markdown2latex )))
+((( ('#' * cell.level + cell.source) | replace('\n', ' ') | parse_citation | markdown2latex )))
 ((* endblock headingcell *))
 
 ((* block rawcell scoped *))
 ((( cell.source | comment_lines )))
 ((* endblock rawcell *))
 
 ((* block unknowncell scoped *))
 unknown type  ((( cell.type )))
 ((* endblock unknowncell *))
 
 ((* block body *))
 
 ((* block bodyBegin *))
 \begin{document}
 ((* endblock bodyBegin *))
 
 ((( super() )))
 
 ((* block bodyEnd *))
+
+((* block bibliography *))
+((* endblock bibliography *))
+
 \end{document}
 ((* endblock bodyEnd *))
 ((* endblock body *))
 
 ((* block header *))
 %% This file was auto-generated by IPython.
 %% Conversion from the original notebook file:
 %%
 \documentclass[11pt,english]{article}
 
 %% This is the automatic preamble used by IPython.  Note that it does *not*
 %% include a documentclass declaration, that is added at runtime to the overall
 %% document.
 
 \usepackage{amsmath}
 \usepackage{amssymb}
 \usepackage{graphicx}
 \usepackage{grffile}
 \usepackage{ucs}
 \usepackage[utf8x]{inputenc}
 
 % Scale down larger images
 \usepackage[export]{adjustbox}
 
 %fancy verbatim
 \usepackage{fancyvrb}
 % needed for markdown enumerations to work
 \usepackage{enumerate}
 
 % Slightly bigger margins than the latex defaults
 \usepackage{geometry}
 \geometry{verbose,tmargin=3cm,bmargin=3cm,lmargin=2.5cm,rmargin=2.5cm}
 
 % Define a few colors for use in code, links and cell shading
 \usepackage{color}
 \definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
 \definecolor{darkorange}{rgb}{.71,0.21,0.01}
 \definecolor{darkgreen}{rgb}{.12,.54,.11}
 \definecolor{myteal}{rgb}{.26, .44, .56}
 \definecolor{gray}{gray}{0.45}
 \definecolor{lightgray}{gray}{.95}
 \definecolor{mediumgray}{gray}{.8}
 \definecolor{inputbackground}{rgb}{.95, .95, .85}
 \definecolor{outputbackground}{rgb}{.95, .95, .95}
 \definecolor{traceback}{rgb}{1, .95, .95}
 
 % new ansi colors
 \definecolor{brown}{rgb}{0.54,0.27,0.07}
 \definecolor{purple}{rgb}{0.5,0.0,0.5}
 \definecolor{darkgray}{gray}{0.25}
 \definecolor{lightred}{rgb}{1.0,0.39,0.28}
 \definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
 \definecolor{lightblue}{rgb}{0.53,0.81,0.92}
 \definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
 \definecolor{lightcyan}{rgb}{0.5,1.0,0.83}
 
 % Framed environments for code cells (inputs, outputs, errors, ...).  The
 % various uses of \unskip (or not) at the end were fine-tuned by hand, so don't
 % randomly change them unless you're sure of the effect it will have.
 \usepackage{framed}
 
 % remove extraneous vertical space in boxes
 \setlength\fboxsep{0pt}
 
 % codecell is the whole input+output set of blocks that a Code cell can
 % generate.
 
 % TODO: unfortunately, it seems that using a framed codecell environment breaks
 % the ability of the frames inside of it to be broken across pages.  This
 % causes at least the problem of having lots of empty space at the bottom of
 % pages as new frames are moved to the next page, and if a single frame is too
 % long to fit on a page, will completely stop latex from compiling the
 % document.  So unless we figure out a solution to this, we'll have to instead
 % leave the codecell env. as empty.  I'm keeping the original codecell
 % definition here (a thin vertical bar) for reference, in case we find a
 % solution to the page break issue.
 
 %% \newenvironment{codecell}{%
 %%     \def\FrameCommand{\color{mediumgray} \vrule width 1pt \hspace{5pt}}%
 %%    \MakeFramed{\vspace{-0.5em}}}
 %%  {\unskip\endMakeFramed}
 
 % For now, make this a no-op...
 \newenvironment{codecell}{}
 
  \newenvironment{codeinput}{%
    \def\FrameCommand{\colorbox{inputbackground}}%
    \MakeFramed{\advance\hsize-\width \FrameRestore}}
  {\unskip\endMakeFramed}
 
 \newenvironment{codeoutput}{%
    \def\FrameCommand{\colorbox{outputbackground}}%
    \vspace{-1.4em}
    \MakeFramed{\advance\hsize-\width \FrameRestore}}
  {\unskip\medskip\endMakeFramed}
 
 \newenvironment{traceback}{%
    \def\FrameCommand{\colorbox{traceback}}%
    \MakeFramed{\advance\hsize-\width \FrameRestore}}
  {\endMakeFramed}
 
 % Use and configure listings package for nicely formatted code
 \usepackage{listingsutf8}
 \lstset{
   language=python,
   inputencoding=utf8x,
   extendedchars=\true,
   aboveskip=\smallskipamount,
   belowskip=\smallskipamount,
   xleftmargin=2mm,
   breaklines=true,
   basicstyle=\small \ttfamily,
   showstringspaces=false,
   keywordstyle=\color{blue}\bfseries,
   commentstyle=\color{myteal},
   stringstyle=\color{darkgreen},
   identifierstyle=\color{darkorange},
   columns=fullflexible,  % tighter character kerning, like verb
 }
 
 % The hyperref package gives us a pdf with properly built
 % internal navigation ('pdf bookmarks' for the table of contents,
 % internal cross-reference links, web links for URLs, etc.)
 \usepackage{hyperref}
 \hypersetup{
   breaklinks=true,  % so long urls are correctly broken across lines
   colorlinks=true,
   urlcolor=blue,
   linkcolor=darkorange,
   citecolor=darkgreen,
   }
 
 % hardcode size of all verbatim environments to be a bit smaller
 \makeatletter 
 \g@addto@macro\@verbatim\small\topsep=0.5em\partopsep=0pt
 \makeatother 
 
 % Prevent overflowing lines due to urls and other hard-to-break entities.
 \sloppy
 
 ((* endblock *))

IPython/nbconvert/templates/latex/sphinx.tplx

@@ -1,469 +1,472 b''
 ((= NBConvert Sphinx-Latex Template
 
 Purpose: Allow export of PDF friendly Latex inspired by Sphinx.  Most of the
        template is derived directly from Sphinx source.
 
 Inheritance: null>display_priority 
 
 Note: For best display, use latex syntax highlighting. =))
 
 ((*- extends 'display_priority.tplx' -*))
 
 
 \nonstopmode
 
 %==============================================================================
 % Declarations
 %==============================================================================
 
 % In order to make sure that the input/output header follows the code it 
 % preceeds, the needspace package is used to request that a certain
 % amount of lines (specified by this variable) are reserved.  If those
 % lines aren't available on the current page, the documenter will break
 % to the next page and the header along with accomanying lines will be
 % rendered together.  This value specifies the number of lines that
 % the header will be forced to group with without a page break.
 ((*- set min_header_lines = 4 -*))
 
 % This is the number of characters that are permitted per line.  It's
 % important that this limit is set so characters do not run off the
 % edges of latex pages (since latex does not always seem smart enough
 % to prevent this in some cases.)  This is only applied to textual output
 ((* if resources.sphinx.outputstyle == 'simple' *))
     ((*- set wrap_size = 85 -*))
 ((* elif resources.sphinx.outputstyle == 'notebook' *))
     ((*- set wrap_size = 70 -*))
 ((* endif *))
 
 %==============================================================================
 % Header
 %==============================================================================
 ((* block header *))
 
 % Header, overrides base
 
     % Make sure that the sphinx doc style knows who it inherits from.
     \def\sphinxdocclass{(((parentdocumentclass)))}
 
     % Declare the document class
     \documentclass[letterpaper,10pt,english]{((( resources.sphinx.texinputs | posix_path )))/sphinx(((documentclass)))}
 
     % Imports
     \usepackage[utf8]{inputenc}
     \DeclareUnicodeCharacter{00A0}{\\nobreakspace}
     \usepackage[T1]{fontenc}
     \usepackage{babel}
     \usepackage{times}
     \usepackage{import}
     \usepackage[((( resources.sphinx.chapterstyle )))]{((( resources.sphinx.texinputs | posix_path )))/fncychap}
     \usepackage{longtable}
     \usepackage{((( resources.sphinx.texinputs | posix_path )))/sphinx}
     \usepackage{multirow}
 
     \usepackage{amsmath}
     \usepackage{amssymb}
     \usepackage{ucs}
     \usepackage{enumerate}
 
     % Used to make the Input/Output rules follow around the contents.
     \usepackage{needspace}
 
     % Pygments requirements
     \usepackage{fancyvrb}
     \usepackage{color}
     % ansi colors additions
     \definecolor{darkgreen}{rgb}{.12,.54,.11}
     \definecolor{lightgray}{gray}{.95}
     \definecolor{brown}{rgb}{0.54,0.27,0.07}
     \definecolor{purple}{rgb}{0.5,0.0,0.5}
     \definecolor{darkgray}{gray}{0.25}
     \definecolor{lightred}{rgb}{1.0,0.39,0.28}
     \definecolor{lightgreen}{rgb}{0.48,0.99,0.0}
     \definecolor{lightblue}{rgb}{0.53,0.81,0.92}
     \definecolor{lightpurple}{rgb}{0.87,0.63,0.87}
     \definecolor{lightcyan}{rgb}{0.5,1.0,0.83}
 
     % Needed to box output/input
     \usepackage{tikz}
         \usetikzlibrary{calc,arrows,shadows}
     \usepackage[framemethod=tikz]{mdframed}
 
     \usepackage{alltt}
 
     % Used to load and display graphics
     \usepackage{graphicx}
     \graphicspath{ {figs/} }
     \usepackage[Export]{adjustbox} % To resize
 
     % used so that images for notebooks which have spaces in the name can still be included
     \usepackage{grffile}
 
 
     % For formatting output while also word wrapping.
     \usepackage{listings}
     \lstset{breaklines=true}
     \lstset{basicstyle=\small\ttfamily}
     \def\smaller{\fontsize{9.5pt}{9.5pt}\selectfont}
 
     %Pygments definitions
     ((( resources.sphinx.pygment_definitions )))
 
     %Set pygments styles if needed...
     ((* if resources.sphinx.outputstyle == 'notebook' *))
         \definecolor{nbframe-border}{rgb}{0.867,0.867,0.867}
         \definecolor{nbframe-bg}{rgb}{0.969,0.969,0.969}
         \definecolor{nbframe-in-prompt}{rgb}{0.0,0.0,0.502}
         \definecolor{nbframe-out-prompt}{rgb}{0.545,0.0,0.0}
 
         \newenvironment{ColorVerbatim}
         {\begin{mdframed}[%
             roundcorner=1.0pt, %
             backgroundcolor=nbframe-bg, %
             userdefinedwidth=1\linewidth, %
             leftmargin=0.1\linewidth, %
             innerleftmargin=0pt, %
             innerrightmargin=0pt, %
             linecolor=nbframe-border, %
             linewidth=1pt, %
             usetwoside=false, %
             everyline=true, %
             innerlinewidth=3pt, %
             innerlinecolor=nbframe-bg, %
             middlelinewidth=1pt, %
             middlelinecolor=nbframe-bg, %
             outerlinewidth=0.5pt, %
             outerlinecolor=nbframe-border, %
             needspace=0pt
         ]}
         {\end{mdframed}}
         
         \newenvironment{InvisibleVerbatim}
         {\begin{mdframed}[leftmargin=0.1\linewidth,innerleftmargin=3pt,innerrightmargin=3pt, userdefinedwidth=1\linewidth, linewidth=0pt, linecolor=white, usetwoside=false]}
         {\end{mdframed}}
 
         \renewenvironment{Verbatim}[1][\unskip]
         {\begin{alltt}\smaller}
         {\end{alltt}}
     ((* endif *))
 
     % Help prevent overflowing lines due to urls and other hard-to-break 
     % entities.  This doesn't catch everything...
     \sloppy
 
     % Document level variables
     \title{((( resources.metadata.name | escape_latex )))}
     \date{((( resources.sphinx.date | escape_latex )))}
     \release{((( resources.sphinx.version | escape_latex )))}
     \author{((( resources.sphinx.author | escape_latex )))}
     \renewcommand{\releasename}{((( resources.sphinx.release | escape_latex )))}
 
     % TODO: Add option for the user to specify a logo for his/her export.
     \newcommand{\sphinxlogo}{}
 
     % Make the index page of the document.
     \makeindex
 
     % Import sphinx document type specifics.
     ((* block sphinxheader *))((* endblock sphinxheader *)) 
 ((* endblock header *))
 
 %==============================================================================
 % Body
 %==============================================================================
 ((* block body *))
 ((* block bodyBegin *))
 % Body
 
     % Start of the document
     \begin{document}
 
         ((* if resources.sphinx.header *))
             \maketitle
         ((* endif *))
 
         ((* block toc *))
             \tableofcontents 
         ((* endblock toc *))
 
         ((* endblock bodyBegin *))
         ((( super() )))
         ((* block bodyEnd *))
 
         \renewcommand{\indexname}{Index}
         \printindex
 
+        ((* block bibliography *))
+        ((* endblock bibliography *))
+
     % End of document
     \end{document}
 ((* endblock bodyEnd *))
 ((* endblock body *))
 
 %==============================================================================
 % Footer
 %==============================================================================
 ((* block footer *))
 ((* endblock footer *))
 
 %==============================================================================
 % Headings
 %
 % Purpose: Format pynb headers as sphinx headers.  Depending on the Sphinx
 %          style that is active, this will change.  Thus sphinx styles will
 %          override the values here.
 %==============================================================================
 ((* block headingcell -*))
     \
     ((*- if cell.level == 1 -*))
         ((* block h1 -*))part((* endblock h1 -*))
     ((*- elif cell.level == 2 -*))
         ((* block h2 -*))chapter((* endblock h2 -*))
     ((*- elif cell.level == 3 -*))
         ((* block h3 -*))section((* endblock h3 -*))
     ((*- elif cell.level == 4 -*))
         ((* block h4 -*))subsection((* endblock h4 -*))
     ((*- elif cell.level == 5 -*))
         ((* block h5 -*))subsubsection((* endblock h5 -*))
     ((*- elif cell.level == 6 -*))
         ((* block h6 -*))paragraph((* endblock h6 -*))
 
     ((= It's important to make sure that underscores (which tend to be common
     in IPYNB file titles) do not make their way into latex.  Sometimes this
     causes latex to barf. =))
     ((*- endif -*))
-    {((( cell.source | markdown2latex )))}
+    {((( cell.source | parse_citation | markdown2latex )))}
 ((*- endblock headingcell *))
 
 %==============================================================================
 % Markdown
 %
 % Purpose: Convert markdown to latex.  Here markdown2latex is explicitly
 %          called since we know we want latex output.
 %==============================================================================
 ((*- block markdowncell scoped-*))
-((( cell.source | markdown2latex )))
+((( cell.source | parse_citation | markdown2latex )))
 ((*- endblock markdowncell -*))
 
 %==============================================================================
 % Rawcell
 %
 % Purpose: Raw text cells allow the user to manually inject document code that 
 %          will not get touched by the templating system.
 %==============================================================================
 ((*- block rawcell *))
 ((( cell.source | wrap_text(wrap_size) )))
 ((* endblock rawcell -*))
 
 %==============================================================================
 % Unknowncell
 %
 % Purpose: This is the catch anything unhandled.  To display this data, we
 %          remove all possible latex conflicts and wrap the characters so they
 %          can't flow off of the page.
 %==============================================================================
 ((* block unknowncell scoped*))
 % Unsupported cell type, no formatting
 ((( cell.source | wrap_text | escape_latex )))
 ((* endblock unknowncell *))
 
 %==============================================================================
 % Input
 %==============================================================================
 ((* block input *))
 
     % Make sure that atleast 4 lines are below the HR
     \needspace{((( min_header_lines )))\baselineskip}
 
     ((* if resources.sphinx.outputstyle == 'simple' *))
 
         % Add a horizantal break, along with break title.
         \vspace{10pt}
         {\scriptsize Input}\\*
         \rule[10pt]{\linewidth}{0.5pt}
         \vspace{-25pt}
 
         % Add contents below.
         ((( cell.input | highlight2latex )))
 
     ((* elif resources.sphinx.outputstyle == 'notebook' *))
         \vspace{6pt}
         ((( write_prompt("In", cell.prompt_number, "nbframe-in-prompt") )))
         \vspace{-2.65\baselineskip}
         \begin{ColorVerbatim}
             \vspace{-0.7\baselineskip}
             ((( cell.input | highlight2latex )))
             ((* if cell.input == None or cell.input == '' *))
                 \vspace{0.3\baselineskip}
             ((* else *))
                 \vspace{-0.2\baselineskip}
             ((* endif *))
         \end{ColorVerbatim}
     ((* endif *))
 ((* endblock input *))
 
 %==============================================================================
 % Output_Group
 %
 % Purpose: Make sure that only one header bar only attaches to the output 
 %          once.  By keeping track of when an input group is started
 %==============================================================================
 ((* block output_group *))
     ((* if cell.outputs.__len__() > 0 *))
 
         % If the first block is an image, minipage the image.  Else
         % request a certain amount of space for the input text.
         ((( iff_figure(cell.outputs[0], "\\begin{minipage}{1.0\\textwidth}", "\\needspace{"  ~ min_header_lines ~ "\\baselineskip}") )))
         
         ((* if resources.sphinx.outputstyle == 'simple' *))
 
             % Add a horizantal break, along with break title.
             \vspace{10pt}
             {\scriptsize Output}\\*
             \rule[10pt]{\linewidth}{0.5pt}
             \vspace{-20pt}
 
             % Add the contents of the first block.
             ((( render_output(cell.outputs[0]) )))
 
             % Close the minipage.
             ((( iff_figure(cell.outputs[0], "\\end{minipage}", "") )))
 
             % Add remainer of the document contents below.
             ((* for output in cell.outputs[1:] *))
                 ((( render_output(output, cell.prompt_number) )))
             ((* endfor *))
         ((* elif resources.sphinx.outputstyle == 'notebook' *))
 
             % Add document contents.
             ((* for output in cell.outputs *))
                 ((( render_output(output, cell.prompt_number) )))
             ((* endfor *))
         ((* endif *))
     ((* endif *))
 ((* endblock *))
 
 %==============================================================================
 % Additional formating
 %==============================================================================
 ((* block data_text *))
 ((( custom_verbatim(output.text) | ansi2latex )))
 ((* endblock *))
 
 ((* block traceback_line *))
 ((( conditionally_center_output( line | indent| strip_ansi ) )))
 ((* endblock traceback_line *))
 
 %==============================================================================
 % Supported image formats
 %==============================================================================
 ((*- block data_png -*))
 ((( conditionally_center_output(insert_graphics(output.png_filename | posix_path)) )))
 ((*- endblock -*))
 
 ((*- block data_jpg -*))
 ((( conditionally_center_output(insert_graphics(output.jpg_filename | posix_path)) )))
 ((*- endblock -*))
 
 ((*- block data_svg -*))
 ((( conditionally_center_output(insert_graphics(output.svg_filename | posix_path)) )))
 ((*- endblock -*))
 
 ((*- block data_pdf -*))
 ((( conditionally_center_output(insert_graphics(output.pdf_filename | posix_path)) )))
 ((*- endblock -*))
 
 ((*- block data_latex *))
 ((* if resources.sphinx.centeroutput *))
     \begin{center}
 ((* endif -*))
 ((( output.latex | strip_math_space )))
 ((*- if resources.sphinx.centeroutput *))
     \end{center}
 ((* endif -*))
 ((*- endblock -*))
 
 %==============================================================================
 % Support Macros
 %==============================================================================
 
 % Name: write_prompt
 % Purpose: Renders an output/input prompt for notebook style pdfs
 ((* macro write_prompt(prompt, number, color) -*))
     \makebox[0.1\linewidth]{\smaller\hfill\tt\color{((( color )))}((( prompt )))\hspace{4pt}{[}((( number ))){]}:\hspace{4pt}}\\*
 ((*- endmacro *))
 
 % Name: render_output
 % Purpose: Renders an output block appropriately.
 ((* macro render_output(output, prompt_number) -*))
     ((*- if output.output_type == 'pyerr' -*))
         ((*- block pyerr scoped *))
             ((( custom_verbatim(super()) )))
         ((* endblock pyerr -*))
     ((*- else -*))
 
         ((* if resources.sphinx.outputstyle == 'notebook' *))
             ((*- if output.output_type == 'pyout' -*))
                 ((( write_prompt("Out", prompt_number, "nbframe-out-prompt") )))
                 \vspace{-2.55\baselineskip}
             ((*- endif -*))
 
             \begin{InvisibleVerbatim}
                 \vspace{-0.5\baselineskip}
         ((*- endif -*))
 
         ((*- block display_data scoped -*))
             ((( super() )))
         ((*- endblock display_data -*))
 
         ((* if resources.sphinx.outputstyle == 'notebook' *))
             \end{InvisibleVerbatim}
         ((*- endif -*))
     ((*- endif -*))
 ((*- endmacro *))
 
 % Name: iff_figure
 % Purpose: If the output block provided is a figure type, the 'true_content'
 %          parameter will be returned.  Else, the 'false_content'. 
 ((* macro iff_figure(output, true_content, false_content) -*))
     ((*- set is_figure = false -*))
     ((*- for type in output | filter_data_type -*))
         ((*- if type in ['pdf', 'svg', 'png', 'jpeg','html']*))
             ((*- set is_figure = true -*))
         ((*- endif -*))
     ((*- endfor -*))
     
     ((* if is_figure -*))
         ((( true_content )))
     ((*- else -*))
         ((( false_content )))
     ((*- endif *))
 ((*- endmacro *))
 
 % Name: custom_verbatim
 % Purpose: This macro creates a verbatim style block that fits the existing
 %          sphinx style more readily than standard verbatim blocks.
 ((* macro custom_verbatim(text) -*))
     \begin{alltt}
     ((*- if resources.sphinx.centeroutput *))\begin{center} ((* endif -*))
 ((( text | wrap_text(wrap_size) | escape_latex )))
     ((*- if resources.sphinx.centeroutput *))\end{center}((* endif -*))
     \end{alltt}
 ((*- endmacro *))
 
 % Name: conditionally_center_output
 % Purpose: This macro centers the output if the output centering is enabled.
 ((* macro conditionally_center_output(text) -*))
     ((* if resources.sphinx.centeroutput *))
         {\centering
     ((* endif *))
     ((( text )))
     ((* if resources.sphinx.centeroutput *))}
     ((* endif *))
 ((*- endmacro *))
 
 % Name: insert_graphics
 % Purpose: This macro will insert an image in the latex document given a path.
 ((* macro insert_graphics(path) -*))
     \begin{center}
     \includegraphics[max size={\textwidth}{\textheight}]{((( path )))}
     \par
     \end{center}
 ((*- endmacro *))