Merge pull request #3863 from damianavila/speaker_notes

Added working speaker notes for slides.

To resume, I fetch the cdn containing the files we need to make speaker notes works. Then I pass this info using the resources dict to the write which output the files in the correct path...
I make some other additions to make this feature an option from the command line, ie:

if you want a simple slideshow:
ipython nbconvert your_slides.ipynb --to slides

if you want a simple served slideshow:
ipython nbconvert your_slides.ipynb --to slides --post serve

if you want to use a local copy of the reveal.js library:
ipython nbconvert your_slides.ipynb --to slides --post serve --local reveal.js

and if you want to use speaker notes:
ipython nbconvert your_slides.ipynb --to slides --post serve --notes True
or
ipython nbconvert your_slides.ipynb --to slides --post serve --notes True --local reveal.js 
but this last one is redundant because if you are using a local reveal.js library the speaker notes are functional by default.

IPython/nbconvert/nbconvertapp.py

@@ -1,320 +1,322 b''
 #!/usr/bin/env python
 """NBConvert is a utility for conversion of .ipynb files.
 
 Command-line interface for the NbConvert conversion utility.
 """
 #-----------------------------------------------------------------------------
 #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
 #-----------------------------------------------------------------------------
 
 # Stdlib imports
 from __future__ import print_function
 
 import logging
 import sys
 import os
 import glob
 
 # From IPython
 from IPython.core.application import BaseIPythonApplication, base_aliases, base_flags
 from IPython.config import catch_config_error, Configurable
 from IPython.utils.traitlets import (
     Unicode, List, Instance, DottedObjectName, Type, CaselessStrEnum,
 )
 from IPython.utils.importstring import import_item
 from IPython.utils.text import dedent
 
 from .exporters.export import get_export_names, exporter_map
 from IPython.nbconvert import exporters, transformers, writers, post_processors
 from .utils.base import NbConvertBase
 from .utils.exceptions import ConversionException
 
 #-----------------------------------------------------------------------------
 #Classes and functions
 #-----------------------------------------------------------------------------
 
 class DottedOrNone(DottedObjectName):
     """
     A string holding a valid dotted object name in Python, such as A.b3._c
     Also allows for None type."""
     
     default_value = u''
 
     def validate(self, obj, value):
         if value is not None and len(value) > 0:
             return super(DottedOrNone, self).validate(obj, value)
         else:
             return value
             
 nbconvert_aliases = {}
 nbconvert_aliases.update(base_aliases)
 nbconvert_aliases.update({
     'to' : 'NbConvertApp.export_format',
     'template' : 'Exporter.template_file',
     'writer' : 'NbConvertApp.writer_class',
     'post': 'NbConvertApp.post_processor_class',
-    'output': 'NbConvertApp.output_base'
+    'output': 'NbConvertApp.output_base',
+    'offline-slides': 'RevealHelpTransformer.url_prefix',
+    'slide-notes': 'RevealHelpTransformer.speaker_notes'
 })
 
 nbconvert_flags = {}
 nbconvert_flags.update(base_flags)
 nbconvert_flags.update({
     'stdout' : (
         {'NbConvertApp' : {'writer_class' : "StdoutWriter"}},
         "Write notebook output to stdout instead of files."
         )
 })
 
 
 class NbConvertApp(BaseIPythonApplication):
     """Application used to convert to and from notebook file type (*.ipynb)"""
 
     name = 'ipython-nbconvert'
     aliases = nbconvert_aliases
     flags = nbconvert_flags
     
     def _log_level_default(self):
         return logging.INFO
     
     def _classes_default(self):
         classes = [NbConvertBase]
         for pkg in (exporters, transformers, writers):
             for name in dir(pkg):
                 cls = getattr(pkg, name)
                 if isinstance(cls, type) and issubclass(cls, Configurable):
                     classes.append(cls)
         return classes
 
     description = Unicode(
         u"""This application is used to convert notebook files (*.ipynb)
         to various other formats.
 
         WARNING: THE COMMANDLINE INTERFACE MAY CHANGE IN FUTURE RELEASES.""")
 
     output_base = Unicode('', config=True, help='''overwrite base name use for output files.
             can only  be use when converting one notebook at a time.
             ''')
 
     examples = Unicode(u"""
         The simplest way to use nbconvert is
         
         > ipython nbconvert mynotebook.ipynb
         
         which will convert mynotebook.ipynb to the default format (probably HTML).
         
         You can specify the export format with `--to`.
         Options include {0}
         
         > ipython nbconvert --to latex mynotebook.ipnynb
 
         Both HTML and LaTeX support multiple output templates. LaTeX includes
         'basic', 'book', and 'article'.  HTML includes 'basic' and 'full'.  You 
         can specify the flavor of the format used.
 
         > ipython nbconvert --to html --template basic mynotebook.ipynb
         
         You can also pipe the output to stdout, rather than a file
         
         > ipython nbconvert mynotebook.ipynb --stdout
 
         A post-processor can be used to compile a PDF
 
         > ipython nbconvert mynotebook.ipynb --to latex --post PDF
         
         You can get (and serve) a Reveal.js-powered slideshow
         
         > ipython nbconvert myslides.ipynb --to slides --post serve
         
         Multiple notebooks can be given at the command line in a couple of 
         different ways:
   
         > ipython nbconvert notebook*.ipynb
         > ipython nbconvert notebook1.ipynb notebook2.ipynb
         
         or you can specify the notebooks list in a config file, containing::
         
             c.NbConvertApp.notebooks = ["my_notebook.ipynb"]
         
         > ipython nbconvert --config mycfg.py
         """.format(get_export_names()))
 
     # Writer specific variables
     writer = Instance('IPython.nbconvert.writers.base.WriterBase',  
                       help="""Instance of the writer class used to write the 
                       results of the conversion.""")
     writer_class = DottedObjectName('FilesWriter', config=True, 
                                     help="""Writer class used to write the 
                                     results of the conversion""")
     writer_aliases = {'fileswriter': 'IPython.nbconvert.writers.files.FilesWriter',
                       'debugwriter': 'IPython.nbconvert.writers.debug.DebugWriter',
                       'stdoutwriter': 'IPython.nbconvert.writers.stdout.StdoutWriter'}
     writer_factory = Type()
 
     def _writer_class_changed(self, name, old, new):
         if new.lower() in self.writer_aliases:
             new = self.writer_aliases[new.lower()]
         self.writer_factory = import_item(new)
 
     # Post-processor specific variables
     post_processor = Instance('IPython.nbconvert.post_processors.base.PostProcessorBase',  
                       help="""Instance of the PostProcessor class used to write the 
                       results of the conversion.""")
 
     post_processor_class = DottedOrNone(config=True, 
                                     help="""PostProcessor class used to write the 
                                     results of the conversion""")
     post_processor_aliases = {'pdf': 'IPython.nbconvert.post_processors.pdf.PDFPostProcessor',
                               'serve': 'IPython.nbconvert.post_processors.serve.ServePostProcessor'}
     post_processor_factory = Type()
 
     def _post_processor_class_changed(self, name, old, new):
         if new.lower() in self.post_processor_aliases:
             new = self.post_processor_aliases[new.lower()]
         if new:
             self.post_processor_factory = import_item(new)
 
 
     # Other configurable variables
     export_format = CaselessStrEnum(get_export_names(),
         default_value="html",
         config=True,
         help="""The export format to be used."""
     )
 
     notebooks = List([], config=True, help="""List of notebooks to convert.
                      Wildcards are supported.
                      Filenames passed positionally will be added to the list.
                      """)
 
     @catch_config_error
     def initialize(self, argv=None):
         super(NbConvertApp, self).initialize(argv)
         self.init_syspath()
         self.init_notebooks()
         self.init_writer()
         self.init_post_processor()
 
 
 
     def init_syspath(self):
         """
         Add the cwd to the sys.path ($PYTHONPATH)
         """
         sys.path.insert(0, os.getcwd())
         
 
     def init_notebooks(self):
         """Construct the list of notebooks.
         If notebooks are passed on the command-line,
         they override notebooks specified in config files.
         Glob each notebook to replace notebook patterns with filenames.
         """
 
         # Specifying notebooks on the command-line overrides (rather than adds)
         # the notebook list
         if self.extra_args:
             patterns = self.extra_args
         else:
             patterns = self.notebooks
 
         # Use glob to replace all the notebook patterns with filenames.
         filenames = []
         for pattern in patterns:
             
             # Use glob to find matching filenames.  Allow the user to convert 
             # notebooks without having to type the extension.
             globbed_files = glob.glob(pattern)
             globbed_files.extend(glob.glob(pattern + '.ipynb'))
             if not globbed_files:
                 self.log.warn("pattern %r matched no files", pattern)
 
             for filename in globbed_files:
                 if not filename in filenames:
                     filenames.append(filename)
         self.notebooks = filenames
 
     def init_writer(self):
         """
         Initialize the writer (which is stateless)
         """
         self._writer_class_changed(None, self.writer_class, self.writer_class)
         self.writer = self.writer_factory(parent=self)
 
     def init_post_processor(self):
         """
         Initialize the post_processor (which is stateless)
         """
         self._post_processor_class_changed(None, self.post_processor_class, 
             self.post_processor_class)
         if self.post_processor_factory:
             self.post_processor = self.post_processor_factory(parent=self)
 
     def start(self):
         """
         Ran after initialization completed
         """
         super(NbConvertApp, self).start()
         self.convert_notebooks()
 
     def convert_notebooks(self):
         """
         Convert the notebooks in the self.notebook traitlet
         """
         # Export each notebook
         conversion_success = 0
 
         if self.output_base != '' and len(self.notebooks) > 1:
             self.log.error(
             """UsageError: --output flag or `NbConvertApp.output_base` config option
             cannot be used when converting multiple notebooks.
             """)
             self.exit(1)
         
         exporter = exporter_map[self.export_format](config=self.config)
 
         for notebook_filename in self.notebooks:
             self.log.info("Converting notebook %s to %s", notebook_filename, self.export_format)
 
             # Get a unique key for the notebook and set it in the resources object.
             basename = os.path.basename(notebook_filename)
             notebook_name = basename[:basename.rfind('.')]
             if self.output_base:
                 notebook_name = self.output_base
             resources = {}
             resources['unique_key'] = notebook_name
             resources['output_files_dir'] = '%s_files' % notebook_name
             self.log.info("Support files will be in %s", os.path.join(resources['output_files_dir'], ''))
 
             # Try to export
             try:
                 output, resources = exporter.from_filename(notebook_filename, resources=resources)
             except ConversionException as e:
                 self.log.error("Error while converting '%s'", notebook_filename,
                       exc_info=True)
                 self.exit(1)
             else:
                 write_resultes = self.writer.write(output, resources, notebook_name=notebook_name)
 
                 #Post-process if post processor has been defined.
                 if hasattr(self, 'post_processor') and self.post_processor:
                     self.post_processor(write_resultes)
                 conversion_success += 1
 
         # If nothing was converted successfully, help the user.
         if conversion_success == 0:
             self.print_help()
             sys.exit(-1)
             
 #-----------------------------------------------------------------------------
 # Main entry point
 #-----------------------------------------------------------------------------
 
 launch_new_instance = NbConvertApp.launch_instance

IPython/nbconvert/templates/slides_reveal.tpl

@@ -1,185 +1,185 b''
 {%- extends 'reveal_internals/slides.tpl' -%}
 
 
 {% block header %}
 <!DOCTYPE html>
 <html>
 <head>
 
 <meta charset="utf-8" />
 <meta http-equiv="X-UA-Compatible" content="chrome=1">
 
 <meta name="apple-mobile-web-app-capable" content="yes" />
 <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
 
 <!-- General and theme style sheets -->
 <link rel="stylesheet" href="{{resources.reveal.url_prefix}}/css/reveal.css">
 <link rel="stylesheet" href="{{resources.reveal.url_prefix}}/css/theme/simple.css" id="theme">
 
 <!-- For syntax highlighting -->
 <link rel="stylesheet" href="{{resources.reveal.url_prefix}}/lib/css/zenburn.css">
 
 <!-- If the query includes 'print-pdf', use the PDF print sheet -->
 <script>
 document.write( '<link rel="stylesheet" href="{{resources.reveal.url_prefix}}/css/print/' + ( window.location.search.match( /print-pdf/gi ) ? 'pdf' : 'paper' ) + '.css" type="text/css" media="print">' );
 </script>
 
 <!--[if lt IE 9]>
 <script src="{{resources.reveal.url_prefix}}/lib/js/html5shiv.js"></script>
 <![endif]-->
 
 {% for css in resources.inlining.css -%}
     <style type="text/css">
     {{ css }}
     </style>
 {% endfor %}
 
 <style type="text/css">
 /* Overrides of notebook CSS for static HTML export */
 .reveal {
 font-size: 20px;
 overflow-y: auto;
 overflow-x: hidden;
 }
 .reveal pre {
 width: 95%;
 padding: 0.4em;
 margin: 0px;
 font-family: monospace, sans-serif;
 font-size: 80%;
 box-shadow: 0px 0px 0px rgba(0, 0, 0, 0);
 }
 .reveal section img {
 border: 0px solid black;
 box-shadow: 0 0 10px rgba(0, 0, 0, 0);
 }
 .reveal .slides {
 text-align: left;
 }
 .reveal.fade {
 opacity: 1;
 }
 div.input_area {
 padding: 0.06em;
 }
 div.code_cell {
 background-color: transparent;
 }
 div.prompt {
 width: 11ex;
 padding: 0.4em;
 margin: 0px;
 font-family: monospace, sans-serif;
 font-size: 80%;
 text-align: right;
 }
 div.output_area pre {
 font-family: monospace, sans-serif;
 font-size: 80%;
 }
 div.output_prompt {
     /* 5px right shift to account for margin in parent container */
     margin: 5px 5px 0 0;
 }
 .rendered_html p {
 text-align: inherit;
 }
 </style>
 
 <!-- Custom stylesheet, it must be in the same directory as the html file -->
 <link rel="stylesheet" href="custom.css">
 
 </head>
 {% endblock header%}
 
 
 {% block body %}
 <body>
 <div class="reveal">
 <div class="slides">
 {{ super() }}
 </div>
 </div>
 
 <!--
 Uncomment the following block and the addthis_widget.js (see below inside dependencies)
 to get enable social buttons.
 -->
 
 <!--
 <div class="addthis_toolbox addthis_floating_style addthis_32x32_style" style="left:20px;top:20px;">
 <a class="addthis_button_twitter"></a>
 <a class="addthis_button_google_plusone_share"></a>
 <a class="addthis_button_linkedin"></a>
 <a class="addthis_button_facebook"></a>
 <a class="addthis_button_more"></a>
 </div>
 -->
 
 <script src="{{resources.reveal.url_prefix}}/lib/js/head.min.js"></script>
 
 <script src="{{resources.reveal.url_prefix}}/js/reveal.js"></script>
 
 <script>
 
 // Full list of configuration options available here: https://github.com/hakimel/reveal.js#configuration
 Reveal.initialize({
 controls: true,
 progress: true,
 history: true,
 
 theme: Reveal.getQueryHash().theme, // available themes are in /css/theme
 transition: Reveal.getQueryHash().transition || 'linear', // default/cube/page/concave/zoom/linear/none
 
 // Optional libraries used to extend on reveal.js
 dependencies: [
 { src: "{{resources.reveal.url_prefix}}/lib/js/classList.js", condition: function() { return !document.body.classList; } },
 { src: "{{resources.reveal.url_prefix}}/plugin/highlight/highlight.js", async: true, callback: function() { hljs.initHighlightingOnLoad(); } },
-{ src: "{{resources.reveal.url_prefix}}/plugin/notes/notes.js", async: true, condition: function() { return !!document.body.classList; } }
+{ src: "{{resources.reveal.notes_prefix}}/plugin/notes/notes.js", async: true, condition: function() { return !!document.body.classList; } }
 // { src: 'http://s7.addthis.com/js/300/addthis_widget.js', async: true},
 ]
 });
 </script>
 
 <!-- MathJax configuration -->
 <script type="text/x-mathjax-config">
 MathJax.Hub.Config({
     tex2jax: {
         inlineMath: [ ['$','$'], ["\\(","\\)"] ],
         displayMath: [ ['$$','$$'], ["\\[","\\]"] ]
     },
     displayAlign: 'left', // Change this to 'center' to center equations.
     "HTML-CSS": {
         styles: {'.MathJax_Display': {"margin": 0}}
     }
 });
 </script>
 <!-- End of mathjax configuration -->
 
 <script>
 //  We wait for the onload function to load MathJax after the page is completely loaded.
 //  MathJax is loaded 1 unit of time after the page is ready.
 //  This hack prevent problems when you load multiple js files (i.e. social button from addthis).
 //
 window.onload = function () {
   setTimeout(function () {
     var script = document.createElement("script");
     script.type = "text/javascript";
     script.src  = "https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS_HTML";
     document.getElementsByTagName("head")[0].appendChild(script);
   },1)
 }
 </script>
 
 <script>
 Reveal.addEventListener( 'slidechanged', function( event ) {
 MathJax.Hub.Rerender(event.currentSlide);
 });
 </script>
 
 </body>
 {% endblock body %}
 
 {% block footer %}
 </html>
 {% endblock footer %}
  No newline at end of file

IPython/nbconvert/transformers/revealhelp.py

@@ -1,61 +1,94 b''
 """Module that pre-processes the notebook for export via Reveal.
 """
 #-----------------------------------------------------------------------------
 # 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
 #-----------------------------------------------------------------------------
 
+import os
+import urllib2
+
 from .base import Transformer
-from IPython.utils.traitlets import Unicode
+from IPython.utils.traitlets import Unicode, Bool
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class RevealHelpTransformer(Transformer):
 
     url_prefix = Unicode('//cdn.jsdelivr.net/reveal.js/2.4.0',
                          config=True,
                          help="""If you want to use a local reveal.js library,
                          use 'url_prefix':'reveal.js' in your config object.""")
 
+    speaker_notes = Bool(False, 
+                         config=True, 
+                         help="""If you want to use the speaker notes 
+                         set this to True.""")
+
     def call(self, nb, resources):
         """
         Called once to 'transform' contents of the notebook.
 
         Parameters
         ----------
         nb : NotebookNode
             Notebook being converted
         resources : dictionary
             Additional resources used in the conversion process.  Allows
             transformers to pass variables into the Jinja engine.
         """
 
         for worksheet in nb.worksheets :
             for index, cell in enumerate(worksheet.cells):
 
                 #Make sure the cell has slideshow metadata.
                 cell.metadata.align_type = cell.get('metadata', {}).get('slideshow', {}).get('align_type', 'Left')
                 cell.metadata.slide_type = cell.get('metadata', {}).get('slideshow', {}).get('slide_type', '-')
 
                 #Get the slide type.  If type is start of subslide or slide,
                 #end the last subslide/slide.
                 if cell.metadata.slide_type in ['slide']:
                     worksheet.cells[index - 1].metadata.slide_helper = 'slide_end'
                 if cell.metadata.slide_type in ['subslide']:
                     worksheet.cells[index - 1].metadata.slide_helper = 'subslide_end'
 
 
         if not isinstance(resources['reveal'], dict):
             resources['reveal'] = {}
         resources['reveal']['url_prefix'] = self.url_prefix
+        resources['reveal']['notes_prefix'] = self.url_prefix
+
+        cdn = 'http://cdn.jsdelivr.net/reveal.js/2.4.0'
+        local = 'local'
+        html_path = 'plugin/notes/notes.html'
+        js_path = 'plugin/notes/notes.js'
+
+        html_infile = os.path.join(cdn, html_path)
+        js_infile = os.path.join(cdn, js_path)
+        html_outfile = os.path.join(local, html_path)
+        js_outfile = os.path.join(local, js_path)
+
+        if self.speaker_notes:
+            if 'outputs' not in resources:
+                resources['outputs'] = {}
+            resources['outputs'][html_outfile] = self.notes_helper(html_infile)
+            resources['outputs'][js_outfile] = self.notes_helper(js_infile)
+            resources['reveal']['notes_prefix'] = local
 
         return nb, resources
+
+    def notes_helper(self, infile):
+        """Helper function to get the content from an url."""
+
+        content = urllib2.urlopen(infile).read()
+
+        return content

docs/source/interactive/nbconvert.rst

@@ -1,212 +1,217 b''
 .. _nbconvert:
 
 Converting notebooks to other formats
 =====================================
 
 Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which 
 allows you to convert an ``.ipynb`` notebook document file into various static 
 formats. 
 
 Currently, ``nbconvert`` is provided as a command line tool, run as a script 
 using IPython. A direct export capability from within the 
 IPython Notebook web app is planned. 
 
 The command-line syntax to run the ``nbconvert`` script is::
 
   $ ipython nbconvert --to FORMAT notebook.ipynb
 
 This will convert the IPython document file ``notebook.ipynb`` into the output 
 format given by the ``FORMAT`` string.
 
 The default output format is html, for which the ``--to`` argument may be 
 omitted::
   
   $ ipython nbconvert notebook.ipynb
 
 IPython provides a few templates for some output formats, and these can be
 specified via an additional ``--template`` argument.
 
 The currently supported export formats are:
 
 * ``--to html``
 
   - ``--template full`` (default)
   
     A full static HTML render of the notebook.
     This looks very similar to the interactive view.
 
   - ``--template basic``
   
     Simplified HTML, useful for embedding in webpages, blogs, etc.
     This excludes HTML headers.
 
 * ``--to latex``
 
   Latex export.  This generates ``NOTEBOOK_NAME.tex`` file,
   ready for export.  You can automatically run latex on it to generate a PDF
   by adding ``--post PDF``.
   
   - ``--template article`` (default)
   
     Latex article, derived from Sphinx's howto template.
 
   - ``--template book``
   
     Latex book, derived from Sphinx's manual template.
 
   - ``--template basic``
   
     Very basic latex output - mainly meant as a starting point for custom templates.
 
 * ``--to slides``
 
   This generates a Reveal.js HTML slideshow.
   It must be served by an HTTP server.  The easiest way to get this is to add
   ``--post serve`` on the command-line.
-
+  If you want to use the speaker notes plugin, just add
+  ``--slide-notes=True`` on the command-line.
+  For low connectivity environments, you can use a local copy of the reveal.js library, 
+  just add ``--offline-slides=reveal.js`` on the command-line, and do not forget to move
+  your downloaded ``reveal.js`` library to the same folder where your slides are located.
+  
 * ``--to markdown``
 
   Simple markdown output.  Markdown cells are unaffected,
   and code cells are placed in triple-backtick (```````) blocks.
 
 * ``--to rst``
 
   Basic reStructuredText output. Useful as a starting point for embedding notebooks
   in Sphinx docs.
 
 * ``--to python``
 
   Convert a notebook to an executable Python script.
   This is the simplest way to get a Python script out of a notebook.
   If there were any magics in the notebook, this may only be executable from
   an IPython session.
   
 .. note::
 
   nbconvert uses pandoc_ to convert between various markup languages,
   so pandoc is a dependency of most nbconvert transforms,
   excluding Markdown and Python.
 
 .. _pandoc: http://johnmacfarlane.net/pandoc/
 
 The output file created by ``nbconvert`` will have the same base name as
 the notebook and will be placed in the current working directory. Any
 supporting files (graphics, etc) will be placed in a new directory with the
 same base name as the notebook, suffixed with ``_files``::
 
   $ ipython nbconvert notebook.ipynb
   $ ls
   notebook.ipynb   notebook.html    notebook_files/
 
 For simple single-file output, such as html, markdown, etc.,
 the output may be sent to standard output with::
     
   $ ipython nbconvert --to markdown notebook.ipynb --stdout
     
 Multiple notebooks can be specified from the command line::
     
   $ ipython nbconvert notebook*.ipynb
   $ ipython nbconvert notebook1.ipynb notebook2.ipynb
     
 or via a list in a configuration file, say ``mycfg.py``, containing the text::
 
   c = get_config()
   c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]
 
 and using the command::
 
   $ ipython nbconvert --config mycfg.py
 
 
 .. _notebook_format:
 
 Notebook JSON file format
 -------------------------
 
 Notebook documents are JSON files with an ``.ipynb`` extension, formatted
 as legibly as possible with minimal extra indentation and cell content broken
 across lines to make them reasonably friendly to use in version-control
 workflows.  You should be very careful if you ever manually edit this JSON
 data, as it is extremely easy to corrupt its internal structure and make the
 file impossible to load.  In general, you should consider the notebook as a
 file meant only to be edited by the IPython Notebook app itself, not for 
 hand-editing.
 
 .. note::
 
      Binary data such as figures are also saved directly in the JSON file.  
      This provides convenient single-file portability, but means that the 
      files can be large; a ``diff`` of binary data is also not very 
      meaningful.  Since the binary blobs are encoded in a single line, they 
      affect only one line of the ``diff`` output, but they are typically very 
      long lines.  You can use the ``Cell | All Output | Clear`` menu option to 
      remove all output from a notebook prior to committing it to version 
      control, if this is a concern.
 
 The notebook server can also generate a pure Python version of your notebook, 
 using the ``File | Download as`` menu option. The resulting ``.py`` file will 
 contain all the code cells from your notebook verbatim, and all Markdown cells 
 prepended with a comment marker.  The separation between code and Markdown
 cells is indicated with special comments and there is a header indicating the
 format version.  All output is removed when exporting to Python.
 
 As an example, consider a simple notebook called ``simple.ipynb`` which 
 contains one Markdown cell, with the content ``The simplest notebook.``, one 
 code input cell with the content ``print "Hello, IPython!"``, and the 
 corresponding output.
 
 The contents of the notebook document ``simple.ipynb`` is the following JSON 
 container::
 
   {
    "metadata": {
     "name": "simple"
    },
    "nbformat": 3,
    "nbformat_minor": 0,
    "worksheets": [
     {
      "cells": [
       {
        "cell_type": "markdown",
        "metadata": {},
        "source": "The simplest notebook."
       },
       {
        "cell_type": "code",
        "collapsed": false,
        "input": "print \"Hello, IPython\"",
        "language": "python",
        "metadata": {},
        "outputs": [
         {
          "output_type": "stream",
          "stream": "stdout",
          "text": "Hello, IPython\n"
         }
        ],
        "prompt_number": 1
       }
      ],
      "metadata": {}
     }
    ]
   }
 
 
 The corresponding Python script is::
 
   # -*- coding: utf-8 -*-
   # <nbformat>3.0</nbformat>
 
   # <markdowncell>
 
   # The simplest notebook.
 
   # <codecell>
 
   print "Hello, IPython"
 
 Note that indeed the output of the code cell, which is present in the JSON 
 container, has been removed in the ``.py`` script.