nbconvert/transformers/sphinx.py

"""Module that allows custom Sphinx parameters to be set on the notebook and
on the 'other' object passed into Jinja.
"""
#-----------------------------------------------------------------------------
# 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
# Used to find Sphinx package location
import sphinx
import os.path

# Used to determine python version
import sys

# Used to set the default date to today's date 
from datetime import date 

# Third-party imports
# Needed for Pygments latex definitions.
from pygments.formatters import LatexFormatter

# Our own imports
# Configurable traitlets
from IPython.utils.traitlets import Unicode, Bool

# Needed to override transformer
from .transformers import (ActivatableTransformer) #TODO

#-----------------------------------------------------------------------------
# Classes and functions
#-----------------------------------------------------------------------------
class SphinxTransformer(ActivatableTransformer):
    """
    Sphinx utility transformer.

    This transformer is used to set variables needed by the latex to build
    Sphinx stylized templates.
    """
    
    interactive = Bool(True, config=True, help="""
    Allows you to define whether or not the Sphinx exporter will prompt
    you for input during the conversion process.  If this is set to false,
    the author, version, release, date, and chapter_style traits should
    be set.
    """)
    
    author = Unicode("Unknown Author", config=True, help="Author name")
    
    version = Unicode("", config=True, help="""Version number
    You can leave this blank if you do not want to render a version number.
    Example: "1.0.0"
    """)
    
    release = Unicode("", config=True, help="""Release name
    You can leave this blank if you do not want to render a release name.
    Example: "Rough Draft"
    """)
    
    publish_date = Unicode("", config=True, help="""Publish date
    This is the date to render on the document as the publish date.
    Leave this blank to default to todays date.  
    Example: "June 12, 1990"
    """)
    
    chapter_style = Unicode("Bjarne", config=True, help="""Sphinx chapter style
    This is the style to use for the chapter headers in the document.
    You may choose one of the following:
        "Bjarne"    (default)
        "Lenny"
        "Glenn"
        "Conny"
        "Rejne"
        "Sonny"    (used for international documents)
    """)
    
    output_style = Unicode("notebook", config=True, help="""Nbconvert Ipython
    notebook input/output formatting style.
    You may choose one of the following:
        "simple     (recommended for long code segments)"
        "notebook"  (default)
    """)
    
    center_output = Bool(False, config=True, help="""
    Optional attempt to center all output.  If this is false, no additional
    formatting is applied.
    """)
    
    use_headers = Bool(True, config=True, help="""
    Whether not a header should be added to the document.
    """)
    
    overridetitle = Unicode("", config=True, help="")
    
    def __call__(self, nb, other):
        """
        Entry
        Since we are not interested in any additional manipulation on a cell
        by cell basis, we do not  call the base implementation.
        """ 
        if self.enabled:
            return self.transform(nb, other)
        else:
            return nb,other

    def transform(self, nb, other):
        """
        Sphinx transformation to apply on each notebook.
        """
         
        # TODO: Add versatile method of additional notebook metadata.  Include
        #       handling of multiple files.  For now use a temporay namespace,
        #       '_draft' to signify that this needs to change.
        if not "_draft" in nb.metadata:
            nb.metadata._draft = {}
            
        if not "sphinx" in other:
            other["sphinx"] = {}

        if self.interactive:
            
            # Prompt the user for additional meta data that doesn't exist currently
            # but would be usefull for Sphinx.
            nb.metadata._draft["author"] = self._prompt_author()
            nb.metadata._draft["version"] = self._prompt_version()
            nb.metadata._draft["release"] = self._prompt_release()
            nb.metadata._draft["date"] = self._prompt_date()
            
            # Prompt the user for the document style.
            other["sphinx"]["chapterstyle"] = self._prompt_chapter_title_style()
            other["sphinx"]["outputstyle"] = self._prompt_output_style()
            
            # Small options
            other["sphinx"]["centeroutput"] = self._prompt_boolean("Do you want to center the output? (false)", False)
            other["sphinx"]["header"] = self._prompt_boolean("Should a Sphinx document header be used? (true)", True)
        else:
            
            # Try to use the traitlets.
            nb.metadata._draft["author"] = self.author
            nb.metadata._draft["version"] = self.version
            nb.metadata._draft["release"] = self.release
            
            # Use todays date if none is provided.
            if len(self.publish_date.strip()) == 0:
                nb.metadata._draft["date"] = date.today().strftime("%B %-d, %Y")
            else:
                nb.metadata._draft["date"] = self.publish_date
            
            # Sphinx traitlets.
            other["sphinx"]["chapterstyle"] = self.chapter_style
            other["sphinx"]["outputstyle"] = self.output_style
            other["sphinx"]["centeroutput"] = self.center_output
            other["sphinx"]["header"] = self.use_headers
            
        # Find and pass in the path to the Sphinx dependencies.
        other["sphinx"]["texinputs"] = os.path.abspath(sphinx.__file__ + "/../texinputs")
        
        # Generate Pygments definitions for Latex 
        other["sphinx"]["pygment_definitions"] = self._generate_pygments_latex_def()
        
        if not (self.overridetitle == None or len(self.overridetitle.strip()) == 0):
            nb.metadata.name = self.overridetitle
        
        # End
        return nb, other 
    
    def _generate_pygments_latex_def(self):
        return LatexFormatter().get_style_defs()       
    
    def _prompt_author(self):
        return  self._input("Author name: ")
    
    def _prompt_version(self):
        return  self._input("Version (ie ""1.0.0""): ")
    
    def _prompt_release(self):
        return  self._input("Release Name (ie ""Rough draft""): ")
    
    def _prompt_date(self):
        default_date = date.today().strftime("%B %-d, %Y")
        user_date = self._input("Date (deafults to \"" + default_date + "\"): ")
        if len(user_date.strip()) == 0:
            user_date = default_date
        return user_date
    
    def _prompt_boolean(self, prompt, default=False):
        response = self._input(prompt)
        response = response.strip().lower()
        
        #Catch 1, true, yes as True
        if len(response) > 0 and (response == "1" or response[0] == "t" or response[0] == "y"):
            return True
        
        #Catch 0, false, no as False
        elif len(response) > 0 and (response == "0" or response[0] == "f" or response[0] == "n"):
            return False
            
        else:
            return default
        
    def _prompt_output_style(self):
        
        # Dictionary of available output styles
        styles = {1: "simple",
                  2: "notebook"}
        
        #Append comments to the menu when displaying it to the user.
        comments = {1: "(recommended for long code segments)",
                    2: "(default)"}
        
        return self._prompt_dictionary(styles, default_style=2, menu_comments=comments)
    
    def _prompt_chapter_title_style(self):
        
        # Dictionary of available Sphinx styles
        styles = {1: "Bjarne",
                  2: "Lenny",
                  3: "Glenn",
                  4: "Conny",
                  5: "Rejne",
                  6: "Sonny"}
        
        #Append comments to the menu when displaying it to the user.
        comments = {1: "(default)",
                    6: "(for international documents)"}
        
        return self._prompt_dictionary(styles, menu_comments=comments)
    
    def _prompt_dictionary(self, choices, default_style=1, menu_comments={}):
                
        # Build the menu that will be displayed to the user with
        # all of the options available. 
        prompt = ""
        for key, value in choices.iteritems():
            prompt += "%d %s " % (key, value)
            if key in menu_comments:
                prompt += menu_comments[key]
            prompt += "\n"
        
        # Continue to ask the user for a style until an appropriate
        # one is specified.
        response = -1
        while (not response in choices):
            try:
                text_response = self._input(prompt)
                
                # Use default option if no input.
                if len(text_response.strip()) == 0:
                    response = default_style
                else:
                    response = int(text_response)
            except:
                print("Error: Value is not an available option.  0 selects the default.\n")
        return choices[response]
          
    def _input(self, prompt_text):
        """
        Prompt the user for input.
        
        The input command will change depending on the version of python
        installed.  To maintain support for 2 and earlier, we must use
        raw_input in that case.  Else use input.
        """
        
        # Try to get the python version.  This command is only available in
        # python 2 and later, so it's important that we catch the exception
        # if the command isn't found.
        try:
            majorversion = sys.version_info[0]
        except:
            majorversion = 1
            
        # Use the correct function to prompt the user for input depending on 
        # what python version the code is running in.
        if majorversion >= 3:
            return input(prompt_text) 
        else:
            return raw_input(prompt_text)