def make_report(self, outcome):
        """Make report in form of two notebooks.

        Use nbdime diff-web to present the difference between reference
        cells and test cells.
        """
        failures = self.getreports('failed')
        if not failures:
            return
        for rep in failures:
            # Check if this is a notebook node
            msg = self._getfailureheadline(rep)
            self.section(msg, rep.longrepr.splitlines()[1])
            self._outrep_summary(rep)
        tmpdir = tempfile.mkdtemp()
        try:
            ref_file = os.path.join(tmpdir, 'reference.ipynb')
            test_file = os.path.join(tmpdir, 'test_result.ipynb')
            with io.open(ref_file, "w", encoding="utf8") as f:
                nbformat.write(self.nb_ref, f)
            with io.open(test_file, "w", encoding="utf8") as f:
                nbformat.write(self.nb_test, f)
            run_server(
                port=0,     # Run on random port
                cwd=tmpdir,
                closable=True,
                on_port=lambda port: browse(
                    port, ref_file, test_file, None))
        finally:
            shutil.rmtree(tmpdir)

def execute_nb(src, dst, allow_errors=False, timeout=1000, kernel_name=None):
    '''
    Execute notebook in `src` and write the output to `dst`

    Parameters
    ----------
    src, dst: str
        path to notebook
    allow_errors: bool
    timeout: int
    kernel_name: str
        defualts to value set in notebook metadata

    Returns
    -------
    dst: str
    '''
    with io.open(src, encoding='utf-8') as f:
        nb = nbformat.read(f, as_version=4)

    ep = ExecutePreprocessor(allow_errors=False,
                             timeout=timeout,
                             kernel_name=kernel_name)
    ep.preprocess(nb, {'metadata': {'path': SOURCE_DIR}})

    with io.open(dst, 'wt', encoding='utf-8') as f:
        nbformat.write(nb, f)
    return dst

def clean_notebook_metadata(root):
    """Cleans the metadata of documentation notebooks."""

    print("Cleaning the metadata of notebooks in '{}'...".format(os.path.abspath(root)))

    for dirpath, dirnames, filenames in os.walk(root):
        is_submitted = _check_if_directory_in_path(dirpath, 'submitted')

        for filename in sorted(filenames):
            if os.path.splitext(filename)[1] == '.ipynb':
                # read in the notebook
                pth = os.path.join(dirpath, filename)
                with io.open(pth, encoding='utf-8') as fh:
                    orig_nb = read(fh, 4)

                # copy the original notebook
                new_nb = clean_notebook(orig_nb)

                # write the notebook back to disk
                os.chmod(pth, stat.S_IRUSR | stat.S_IWUSR)
                with io.open(pth, mode='w', encoding='utf-8') as fh:
                    write(new_nb, fh, 4)

                if orig_nb != new_nb:
                    print("Cleaned '{}'".format(pth))

def make_open_notebook(options):
    """
    Generate an ipython notebook and open it in the browser.
    Return system exit code.

    Raise:
        RuntimeError if jupyther is not in $PATH
    """
    import nbformat
    nbf = nbformat.v4
    nb = nbf.new_notebook()

    nb.cells.extend([
        nbf.new_markdown_cell("# This is an auto-generated notebook for %s" % os.path.relpath(filepath)),
        nbf.new_code_cell("""\
from __future__ import print_function, division, unicode_literals, absolute_import
%matplotlib notebook
#import numpy as np
#import seaborn as sns
from abipy import abilab\
"""),

    nbf.new_code_cell("abifile = abilab.abiopen('%s')" % options.filepath)
    ])

    _, nbpath = tempfile.mkstemp(suffix='.ipynb', text=True)

    with io.open(nbpath, 'wt', encoding="utf8") as f:
        nbformat.write(nb, f)

    if which("jupyter") is None:
        raise RuntimeError("Cannot find jupyter in PATH. Install it with `pip install`")
    return os.system("jupyter notebook %s" % nbpath)

def _notebook_run(path):
    """Execute a notebook via nbconvert and collect output.
       :returns (parsed nb object, execution errors)
    """
    kernel_name = 'python%d' % sys.version_info[0]
    this_file_directory = os.path.dirname(__file__)
    errors = []
    with tempfile.NamedTemporaryFile(suffix=".ipynb", mode='wt') as fout:
        with open(path) as f:
            nb = nbformat.read(f, as_version=4)
            nb.metadata.get('kernelspec', {})['name'] = kernel_name
            ep = ExecutePreprocessor(kernel_name=kernel_name, timeout=10)

            try:
                ep.preprocess(nb, {'metadata': {'path': this_file_directory}})
            except CellExecutionError as e:
                if "SKIP" in e.traceback:
                    print(str(e.traceback).split("\n")[-2])
                else:
                    raise e
            except RuntimeError as e:
                print(e)

            finally:
                nbformat.write(nb, fout)

    return nb, errors

    def test_very_long_cells(self):
        """
        Torture test that long cells do not cause issues
        """
        lorem_ipsum_text = textwrap.dedent("""\
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec
          dignissim, ipsum non facilisis tempus, dui felis tincidunt metus,
          nec pulvinar neque odio eget risus. Nulla nisi lectus, cursus
          suscipit interdum at, ultrices sit amet orci. Mauris facilisis
          imperdiet elit, vitae scelerisque ipsum dignissim non. Integer
          consequat malesuada neque sit amet pulvinar. Curabitur pretium
          ut turpis eget aliquet. Maecenas sagittis lacus sed lectus
          volutpat, eu adipiscing purus pulvinar. Maecenas consequat
          luctus urna, eget cursus quam mollis a. Aliquam vitae ornare
          erat, non hendrerit urna. Sed eu diam nec massa egestas pharetra
          at nec tellus. Fusce feugiat lacus quis urna sollicitudin volutpat.
          Quisque at sapien non nibh feugiat tempus ac ultricies purus.
           """)
        lorem_ipsum_text = lorem_ipsum_text.replace("\n"," ") + "\n\n"
        large_lorem_ipsum_text = "".join([lorem_ipsum_text]*3000)

        notebook_name = "lorem_ipsum_long.ipynb"
        nb = v4.new_notebook(
            cells=[
                    v4.new_markdown_cell(source=large_lorem_ipsum_text)
            ]
        )

        with TemporaryDirectory() as td:
            nbfile = os.path.join(td, notebook_name)
            with open(nbfile, 'w') as f:
                write(nb, f, 4)

            (output, resources) = LatexExporter(template_file='article').from_filename(nbfile)
            assert len(output) > 0

def nb_to_html(root, template='basic', version=4, timeout=600, kernel='python3'):
    '''
    This functions executes a Jupyter notebook and creates the related
    HTML file.

    Args:
        root (str): name of the file without the .ipynb extension
        template (str): name of the template (to be in the current folder as template.tpl)
        version (int): version of the notebook
        timeout (float): maximum time spent per cell
        kernel (str)

    Returns:
        None

    The function executes root.ipynb into root_exe.ipynb and creates the file root.html.
    '''
    with open(root + '.ipynb') as f:
        nb = nbformat.read(f, as_version=version)

    ep = ExecutePreprocessor(timeout=timeout, kernel_name=kernel)
    ep.preprocess(nb, {'metadata': {'path': '.'}})

    with open(root + '_exe.ipynb', 'wt') as f:
        nbformat.write(nb, f)

    html_exporter = HTMLExporter()
    html_exporter.template_file = template

    with open(root + '_exe.ipynb', mode='r') as f:
        notebook = nbformat.reads(''.join(f.readlines()), as_version=version)
        (body, _) = html_exporter.from_notebook_node(notebook)
        codecs.open(root + '.html', 'w', encoding='utf-8').write(body)

def clear_notebooks(root):
    """Clear the outputs of documentation notebooks."""

    # cleanup ignored files
    run(['git', 'clean', '-fdX', root])

    print("Clearing outputs of notebooks in '{}'...".format(os.path.abspath(root)))
    preprocessor = ClearOutputPreprocessor()

    for dirpath, dirnames, filenames in os.walk(root):
        is_submitted = _check_if_directory_in_path(dirpath, 'submitted')

        for filename in sorted(filenames):
            if os.path.splitext(filename)[1] == '.ipynb':
                # read in the notebook
                pth = os.path.join(dirpath, filename)
                with open(pth, 'r') as fh:
                    orig_nb = read(fh, 4)

                # copy the original notebook
                new_nb = deepcopy(orig_nb)

                # check outputs of all the cells
                if not is_submitted:
                    new_nb = preprocessor.preprocess(new_nb, {})[0]

                # clear metadata
                new_nb.metadata = {}

                # write the notebook back to disk
                with open(pth, 'w') as fh:
                    write(new_nb, fh, 4)

                if orig_nb != new_nb:
                    print("Cleared '{}'".format(pth))

    def write_notebook(self, include_html=True):
        suffix = "_responses_with_names" if self.include_usernames else "_responses"
        nb_name = self.nb_name_stem + suffix
        output_file = os.path.join(PROCESSED_NOTEBOOK_DIR, nb_name + '.ipynb')
        html_output = os.path.join(PROCESSED_NOTEBOOK_DIR, nb_name + '.html')

        remove_duplicate_answers = not self.include_usernames

        filtered_cells = []
        for prompt in self.question_prompts:
            filtered_cells += prompt.cells
            answers = prompt.answers_without_duplicates if remove_duplicate_answers else prompt.answers
            for gh_username, response_cells in answers.items():
                if self.include_usernames:
                    filtered_cells.append(
                        NotebookUtils.markdown_heading_cell(self.gh_username_to_fullname(gh_username), 4))
                filtered_cells.extend(response_cells)

        answer_book = deepcopy(self.template)
        answer_book['cells'] = filtered_cells
        nb = nbformat.from_dict(answer_book)

        print "Writing", output_file
        with io.open(output_file, 'wt') as fp:
            nbformat.write(nb, fp, version=4)

        if include_html:
            # TODO why is the following necessary?
            nb = nbformat.reads(nbformat.writes(nb, version=4), as_version=4)
            html_content, _ = nbconvert.export_html(nb)
            print "Writing", html_output
            with io.open(html_output, 'w') as fp:
                fp.write(html_content)

    def setUp(self):
        nbdir = self.notebook_dir
        subdir = pjoin(nbdir, 'foo')

        try:
            os.mkdir(subdir)
        except OSError as e:
            # Deleting the folder in an earlier test may have failed
            if e.errno != errno.EEXIST:
                raise
        self.addCleanup(partial(shutil.rmtree, subdir, ignore_errors=True))

        with io.open(pjoin(subdir, 'nb1.ipynb'), 'w', encoding='utf-8') as f:
            nb = new_notebook()
            write(nb, f, version=4)

        self.sess_api = SessionAPI(self.request)

        @self.addCleanup
        def cleanup_sessions():
            for session in self.sess_api.list().json():
                self.sess_api.delete(session['id'])

            # This is necessary in some situations on Windows: without it, it
            # fails to delete the directory because something is still using
            # it. I think there is a brief period after the kernel terminates
            # where Windows still treats its working directory as in use. On my
            # Windows VM, 0.01s is not long enough, but 0.1s appears to work
            # reliably.  -- TK, 15 December 2014
            time.sleep(0.1)

    def check_stuff_gets_embedded(self, nb, exporter_name, to_be_included=[]):
        nb_basename = 'notebook'
        nb_src_filename = nb_basename + '.ipynb'
        with io.open(nb_src_filename, 'w', encoding='utf-8') as f:
            write(nb, f, 4)

        # convert with default exporter
        self.nbconvert('--to {} "{}"'.format('html', nb_src_filename))
        nb_dst_filename = nb_basename + '.html'
        assert os.path.isfile(nb_dst_filename)
        statinfo = os.stat(nb_dst_filename)

        os.remove(nb_dst_filename)

        # convert with embedding exporter
        self.nbconvert('--to {} "{}"'.format(exporter_name, nb_src_filename))
        statinfo_e = os.stat(nb_dst_filename)
        assert os.path.isfile(nb_dst_filename)

        assert statinfo_e.st_size > statinfo.st_size

        with io.open(nb_dst_filename, 'r', encoding='utf-8') as f:
            embedded_nb = f.read()

        for txt in to_be_included:
            assert txt in embedded_nb

def main():
    arguments = docopt(__doc__, version='nbgen 2.0')

    cmd = subprocess.run([arguments["<path>"]] + arguments["<arguments>"], stdout=subprocess.PIPE)
    cmd.check_returncode()
    cells = json.loads(cmd.stdout.decode("utf-8"))

    nb_dict = {
      "metadata": {},
      "nbformat": 4,
      "nbformat_minor": 0,
      "cells": cells,
    }
    notebook = nbformat.from_dict(nb_dict)

    ep = ExecutePreprocessor(timeout=600, kernel_name='python3')
    ep.preprocess(notebook, {'metadata': {}})

    if arguments["nb"]:
        nbformat.write(notebook, "{}.ipynb".format(arguments["<name>"]))

    elif arguments["slides"]:
        config = Config()
        reveal_cdn = "https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.3.0/"
        config.SlidesExporter.reveal_url_prefix = (arguments["--reveal"] or reveal_cdn)

        slides, __ = export_slides(nb=notebook, config=config)
        with open("{}.html".format(arguments["<name>"]), "w") as html_file:
            html_file.write(slides)

def build_iab_main(input_dir, output_dir, out_format, ext, css=None):
    """ Convert md sources to readable book content, maintaining dir structure.

        A few additional processing steps happen here:
         * Add Table of Contents to the top of each section.
         * Create links from sha1 aliases.

        Parameters
        ----------
        input_dir : str
            Root path for the markdown files.
        output_dir : str
            Root path for the output files.
        out_format : str
            The ipymd format that output files should be written in (for example,
            ``notebook``).
        ext : str
            The extension to use for output files.

    """
    # Walk the input root directory. We only care about root and files
    # inside this loop (nothing happens with dirs).
    for unit_number, (unit, chapters) in enumerate(input_dir):
        # Iterate over the files in the current root.
        if unit_number == 0:
            unit_path = ''
        else:
            unit_path = str(unit_number) + '/'
        for chapter_number, content_md in enumerate(chapters):
            if chapter_number == 0:
                chapter_path = 'index'
            else:
                chapter_path = str(chapter_number)
            path = '%s%s' % (unit_path, chapter_path)
            # Convert it from markdown
            output_s = ipymd.convert(content_md, from_='markdown', to='notebook')
            # define the output filepath
            output_fp = get_output_fp(output_dir, path, ext)
            try:
                os.makedirs(os.path.split(output_fp)[0])
            except OSError:
                pass

            # write the output ipynb
            nbformat.write(output_s, output_fp)

    if out_format == 'html' or out_format == 's3':
        c = Config()
        c.ExecutePreprocessor.timeout = 600
        html_exporter = HTMLExporter(preprocessors=['nbconvert.preprocessors.execute.ExecutePreprocessor'],
                                     config=c)

        for root, dirs, files in os.walk(output_dir):
            if css:
                shutil.copy(css, os.path.join(root, 'custom.css'))
            for f in files:
                html_out, _ = html_exporter.from_filename(os.path.join(root, f))
                output_fn = os.path.splitext(f)[0] + ext
                output_fp = os.path.join(root, output_fn)
                open(output_fp, 'w').write(html_out)

def test_tutorial_nb(file_path):
    """Run tutorial jupyter notebook to catch any execution error.

    Parameters
    ----------
    file_path : str
        path of tutorial markdown file
    """
    tutorial_name = os.path.basename(file_path)
    notebook = nbformat.read(file_path + '.ipynb', as_version=4)
    eprocessor = ExecutePreprocessor(timeout=1800)
    try:
        eprocessor.preprocess(notebook, {'metadata': {}})
    except Exception as err:
        err_msg = str(err)
        fail_dict[tutorial_name] = err_msg
    finally:
        output_nb = open("output.txt", mode='w')
        nbformat.write(notebook, output_nb)
        output_nb.close()
        output_nb = open("output.txt", mode='r')
        for line in output_nb:
            if "Warning:" in line:
                fail_dict[tutorial_name] = "%s has warning." % (tutorial_name)
                return

    def _runTest(self):
        kernel = 'python%d' % sys.version_info[0]
        cur_dir = os.path.dirname(self.nbfile)

        with open(self.nbfile) as f:
            nb = nbformat.read(f, as_version=4)
            if self.cov:
                covdict = {'cell_type': 'code', 'execution_count': 1,
                           'metadata': {'collapsed': True}, 'outputs': [],
                           'nbsphinx': 'hidden',
                           'source': 'import coverage\n'
                                     'coverage.process_startup()\n'
                                     'import sys\n'
                                     'sys.path.append("{0}")\n'.format(cur_dir)
                           }
                nb['cells'].insert(0, nbformat.from_dict(covdict))

            exproc = ExecutePreprocessor(kernel_name=kernel, timeout=600)

            try:
                run_dir = os.getenv('WRADLIB_BUILD_DIR', cur_dir)
                exproc.preprocess(nb, {'metadata': {'path': run_dir}})
            except CellExecutionError as e:
                raise e

        if self.cov:
            nb['cells'].pop(0)

        with io.open(self.nbfile, 'wt') as f:
            nbformat.write(nb, f)

        self.assertTrue(True)

def _notebook_run(path):
    """Execute a notebook via nbconvert and collect output.
       :returns (parsed nb object, execution errors)
    """
    kernel_name = "python%d" % sys.version_info[0]
    this_file_directory = os.path.dirname(__file__)
    errors = []
    with tempfile.NamedTemporaryFile(suffix=".ipynb", mode="wt") as fout:
        with open(path) as f:
            nb = nbformat.read(f, as_version=4)
            nb.metadata.get("kernelspec", {})["name"] = kernel_name
            ep = ExecutePreprocessor(kernel_name=kernel_name, timeout=10)

            try:
                ep.preprocess(nb, {"metadata": {"path": this_file_directory}})
            except CellExecutionError as e:
                if "SKIP" in e.traceback:
                    print(str(e.traceback).split("\n")[-2])
                else:
                    raise e
            except TimeoutError as e:
                print(e)

            finally:
                nbformat.write(nb, fout)
        # nb = nbformat.read(fout, nbformat.current_nbformat)

    # errors = errors.extend(
    # [output for cell in nb.cells if "outputs" in cell
    # for output in cell["outputs"] if output.output_type == "error"])

    return nb, errors

def execute_nb(src, dst, allow_errors=False, timeout=1000, kernel_name=''):
    """
    Execute notebook in `src` and write the output to `dst`

    Parameters
    ----------
    src, dst: str
        path to notebook
    allow_errors: bool
    timeout: int
    kernel_name: str
        defualts to value set in notebook metadata

    Returns
    -------
    dst: str
    """
    import nbformat
    from nbconvert.preprocessors import ExecutePreprocessor

    with io.open(src, encoding='utf-8') as f:
        nb = nbformat.read(f, as_version=4)

    ep = ExecutePreprocessor(allow_errors=allow_errors,
                             timeout=timeout,
                             kernel_name=kernel_name)
    ep.preprocess(nb, resources={})

    with io.open(dst, 'wt', encoding='utf-8') as f:
        nbformat.write(nb, f)
    return dst

    def dojo_nbcompare(self, what="all", **kwargs):
        """
        Generate an ipython notebook to compare the results in the dojoreport (calls dojo_compare).
        """
        paths = [p.path for p in self]
        import nbformat
        nbf = nbformat.v4
        nb = nbf.new_notebook()

        nb.cells.extend([
            #nbf.new_markdown_cell("# This is an auto-generated notebook for %s" % os.path.basename(pseudopath)),
            nbf.new_code_cell("""\
from __future__ import print_function, division, unicode_literals
%matplotlib notebook"""),

            nbf.new_code_cell("""\
from pseudo_dojo.core.pseudos import DojoTable
pseudos = DojoTable(%s)""" % str(paths)),
            nbf.new_code_cell("pseudos.dojo_compare(what='%s')" % what),
        ])

        _, nbpath = tempfile.mkstemp(suffix='.ipynb', text=True)

        import io
        with io.open(nbpath, 'wt', encoding="utf8") as f:
            nbformat.write(nb, f)

        if which("jupyter") is None:
            raise RuntimeError("Cannot find jupyter in PATH. Install it with `pip install`")
        return os.system("jupyter notebook %s" % nbpath)

    def notebook(self, s):
        """Export and convert IPython notebooks.

        This function can export the current IPython history to a notebook file.
        For example, to export the history to "foo.ipynb" do "%notebook foo.ipynb".

        The -e or --export flag is deprecated in IPython 5.2, and will be
        removed in the future.
        """
        args = magic_arguments.parse_argstring(self.notebook, s)

        from nbformat import write, v4

        cells = []
        hist = list(self.shell.history_manager.get_range())
        if(len(hist)<=1):
            raise ValueError('History is empty, cannot export')
        for session, execution_count, source in hist[:-1]:
            cells.append(v4.new_code_cell(
                execution_count=execution_count,
                source=source
            ))
        nb = v4.new_notebook(cells=cells)
        with io.open(args.filename, 'w', encoding='utf-8') as f:
            write(nb, f, version=4)

def execute_nb(src, dst, allow_errors=False, timeout=1000, kernel_name=None):
    """
    Execute notebook in `src` and write the output to `dst`

    Parameters
    ----------
    src, dst: str
        path to notebook
    allow_errors: bool
    timeout: int
    kernel_name: str
        defualts to value set in notebook metadata

    Returns
    -------
    dst: str
    """
    with io.open(src, encoding="utf-8") as f:
        nb = nbformat.read(f, as_version=4)

    ep = ExecutePreprocessor(allow_errors=allow_errors, timeout=timeout, kernel_name=kernel_name)
    ep.preprocess(nb, {"metadta": {"path": "notebooks/"}})

    with io.open(dst, "wt", encoding="utf-8") as f:
        nbformat.write(nb, f)
    return dst