notebook.py

# -*- coding: utf-8 -*-
"""
Notebook plugin.

This plugin lets you easily include html-rendered IPython notebooks as part
of your Hyde site.  This plugin requires IPython version 1.x

To use, simply add the following to your site.yaml file:

plugins:
    - hyde.ext.plugins.notebook.NotebookPlugin

Then where there are notebooks in your site tree, an HTML version will be
deployed.  If this is the contents of your site:

    site.yaml
    contents/
        index.html     <-- normal files ignored
        notebook.ipynb <-- ipynb extensions converted

Then the deploy directory will look like this:

    deploy/
        index.html     <-- files generated by hyde
        notebook.html  <-- converted by IPython.nbconvert
        notebook.ipynb <-- raw notebook
"""
# TODO: - allow inserting notebooks into templates

import os
import shutil

from hyde.plugin import Plugin
from hyde.model import Expando
from commando.util import getLoggerWithNullHandler
from fswrap import File, Folder

logger = getLoggerWithNullHandler('hyde.ext.plugins.notebook')

try:
    import IPython
    if IPython.__version__[0] != '1':
        raise ImportError("IPython version 1.x required")
except ImportError:
    logger.error("The notebook plugin requires IPython version 1.x")
    logger.error("`pip install -U ipython` to get it.")
    raise

from IPython.nbformat import current as nbformat
from IPython.nbconvert.exporters import HTMLExporter


class NotebookPlugin(Plugin):
    """The plugin class for converting IPython notebooks to HTML"""
    suffix = "ipynb"

    def __init__(self, site):
        self._notebook_config = None
        super(NotebookPlugin, self).__init__(site)

    @property
    def plugin_name(self):
        """The name of the plugin"""
        return "notebook"

    @property
    def settings(self):
        """Settings for this plugin"""
        settings = Expando({})
        try:
            user_settings = getattr(self.site.config, self.plugin_name)
        except AttributeError:
            pass
        else:
            for name in dir(user_settings):
                if not name.startswith("_"):
                    setattr(settings, name, getattr(user_settings, name))
        return settings

    def begin_site(self):
        """Event hook for when site processing begins"""
        settings = self.settings

        for resource in self.site.content.walk_resources():
            if resource.source_file.path.endswith(self.suffix):
                new_name = (resource.source_file.name_without_extension
                            + ".html")
                target_folder = File(resource.relative_deploy_path).parent
                resource.relative_deploy_path = target_folder.child(new_name)
                

    def begin_text_resource(self, resource, text):
        """Event hook for processing an individual resource."""
        if not resource.source_file.path.endswith(self.suffix):
            return text
            
        # Copy the raw notebook file to the deploy directory
        raw_file_dest = os.path.join(
            resource.site.config.deploy_root,
            File(resource.relative_deploy_path).parent.child(
                resource.source_file.name))

        shutil.copy(resource.source_file.path, raw_file_dest)
            
        # use nbconvert to convert to HTML
        exporter = HTMLExporter(template_file='full')
        nb_json = nbformat.reads_json(text)
        (body, resources) = exporter.from_notebook_node(nb_json)

        # return the converted text
        return body