Merge pull request #3831 from minrk/nbdoc

update nbconvert doc with new CLI

docs/source/interactive/nbconvert.rst

@@ -0,0 +1,212 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.
+
+* ``--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.
+

docs/source/interactive/index.rst

@@ -11,7 +11,7 b' Using IPython for interactive work'
    shell
    qtconsole
    notebook
-   converting_notebooks
+   nbconvert
    working_remotely
 
 

docs/source/interactive/notebook.rst

@@ -477,26 +477,7 b' setup for IPython to work correctly hand in hand with ``matplotlib``; it does'
 *not*, however, actually execute any Python ``import`` commands, that is, no 
 names are added to the namespace.
 
-For more agile *interactive* use of the notebook space, an alternative magic, 
-``%pylab``, is provided. This does the same work as the ``%matplotlib`` magic, 
-but *in addition* it automatically executes a standard sequence of ``import`` 
-statements required to work with the ``%matplotlib`` library, importing the 
-following names into the namespace:
-
-  ``numpy`` as ``np``; ``matplotlib.pyplot`` as ``plt``;
-  ``matplotlib``, ``pylab`` and ``mlab`` from ``matplotlib``; and *all names* 
-  from within ``numpy`` and ``pylab``. 
-
-However, the use of ``%pylab`` is discouraged, since names coming from 
-different packages may collide. In general, the use of ``from package import 
-*`` is discouraged. A better option is then::
-  
-    %pylab --no-import-all
-
-which imports the  names listed above, but does *not* perform this 
-``import *`` imports.
-
-If the ``%matplotlib`` or ``%pylab` magics are called without an argument, the 
+If the ``%matplotlib`` magic is called without an argument, the 
 output of a plotting command is displayed using the default ``matplotlib`` 
 backend in a separate window. Alternatively, the backend can be explicitly 
 requested using, for example::
@@ -504,7 +485,7 b' requested using, for example::'
   %matplotlib gtk
 
 A particularly interesting backend is the ``inline`` backend.
-This is applicable only for the IPython Notebook and the IPython Qtconsole. 
+This is applicable only for the IPython Notebook and the IPython QtConsole.
 It can be invoked as follows::
 
   %matplotlib inline