update nbconvert doc

update to new CLI

remove documentation of ill-advised `--script` option.

docs/source/interactive/converting_notebooks.rst

@@ -10,65 +10,66 @@ 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. In the future, a direct export capability from within the 
+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 --format=FORMAT notebook.ipynb
+  $ 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 ``--format`` modifier may be 
+The default output format is html, for which the ``--to`` argument may be 
 omitted::
   
   $ ipython nbconvert notebook.ipynb
 
-The currently supported export formats are the following:
+IPython provides a few templates for some output formats, and these can be
+specified via an additional ``--template`` argument.
 
-* HTML:
+The currently supported export formats are:
 
-  - **full_html**:
+* ``--to html``
-    Standard HTML
 
-  - **simple_html**:
+  - ``--template full`` (default)
-    Simplified HTML
+    A full static HTML render of the notebook.
+    This looks very similar to the interactive view.
 
-  - **reveal**:
+  - ``--template basic``
-    HTML slideshow presentation for use with the ``reveal.js`` package
+    Simplified HTML, useful for embedding in webpages, blogs, etc.
+    This excludes HTML headers.
 
-* PDF:
+* ``--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.
 
-  - **sphinx_howto**:
+  - ``--template book``
-    The format for Sphinx_ HOWTOs; similar to an ``article`` in LaTeX
+    Latex book, derived from Sphinx's manual template.
 
-  - **sphinx_manual**:
+  - ``--template basic``
-    The format for Sphinx_ manuals; similar to a ``book`` in LaTeX 
+    Very basic latex output - mainly meant as a starting point for custom templates.
 
-  - **latex**:
+* ``--to slides``
-    An article formatted completely using LaTeX
 
-* Markup:
+  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.
 
-  - **rst**:
+* ``--to markdown`` Simple markdown
-    reStructuredText_ markup
 
-  - **markdown**:
+* ``--to rst`` reStructuredText
-    Markdown_ markup
 
-.. _Sphinx: http://sphinx-doc.org/
+* ``--to python`` Convert a notebook to an executable Python script.
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+  This is the simplest way to get a Python script out of a notebook.
-.. _Markdown: http://daringfireball.net/projects/markdown/syntax
+  If there were any magics in the notebook, this may only be executable from
+  an IPython session.
 
-* Python:
+The output file created by ``nbconvert`` will have the same base name as
-
-    Comments out all the non-Python code to produce a ``.py`` Python
-    script with just the code content. Currently the output includes IPython 
-    magics, and so can be run with ``ipython``, after changing the extension 
-    of the script to ``.ipy``.
-    
-The files 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``::
@@ -77,23 +78,10 @@ same base name as the notebook, suffixed with ``_files``::
   $ ls
   notebook.ipynb   notebook.html    notebook_files/
 
-Each of the options for PDF export produces as an intermediate step a LaTeX 
+For simple single-file output, such as html, markdown, etc.,
-``.tex`` file with the same basename as the notebook, as well as individual 
+the output may be sent to standard output with::
-files for each figure, and ``.text`` files with textual output from running
-code cells.
-
-To actually produce the final PDF file, run the following commands::
-  
-  $ ipython nbconvert --format=latex notebook.ipynb
-  $ pdflatex notebook
-
-This requires a local installation of LaTeX on your machine.
-The output is a PDF file ``notebook.pdf``, also placed inside the 
-``nbconvert_build`` subdirectory.
-
-Alternatively, the output may be sent to standard output with::
     
-  $ ipython nbconvert notebook.ipynb --stdout
+  $ ipython nbconvert --to markdown notebook.ipynb --stdout
     
 Multiple notebooks can be specified from the command line::
     
@@ -110,68 +98,11 @@ and using the command::
   $ ipython nbconvert --config mycfg.py
 
 
-Extracting standard Python files from notebooks
------------------------------------------------
-``.ipynb`` notebook document files are plain text files which store a 
-representation in JSON format of the contents of a notebook space. As such, 
-they are not valid ``.py`` Python scripts, and so can be neither imported 
-directly with ``import`` in Python, nor run directly as a standard Python 
-script (though both of these are possible with simple workarounds).
-
-
-To extract the Python code from within a notebook document, the simplest 
-method is to use the ``File | Download as | Python (.py)`` menu item; the 
-resulting ``.py`` script will be downloaded to your browser's  default 
-download location.
-
-An alternative is to pass an argument to the IPython Notebook, from the moment 
-when it is originally started, specifying that whenever it saves an ``.ipynb`` 
-notebook document, it should, at the same time, save the corresponding 
- ``.py`` script. To do so, you can execute the following command::
-
-  $ ipython notebook --script
-
-or you can set this option permanently in your configuration file with::
-
-  c = get_config()
-  c.NotebookManager.save_script=True
-
-The result is that standard ``.py`` files are also now generated, which 
-can be ``%run``, imported from regular IPython sessions or other notebooks, or 
-executed at the command line, as usual.  Since the raw code you have typed is 
-exported, you must avoid using syntax such as IPython magics and other 
-IPython-specific extensions to the language for the files to be able to be 
-successfully imported.
-.. or you can change the script's extension to ``.ipy`` and run it with::
-..
-..  $ ipython script.ipy
-
-In normal Python practice, the standard way to differentiate importable code 
-in a Python script from the "executable" part of a script is to use the 
-following idiom at the start of the executable part of the code::
-
-  if __name__ == '__main__'
-
-    # rest of the code...
-  
-Since all cells in the notebook are run as top-level code, you will need to
-similarly protect *all* cells that you do not want executed when other scripts
-try to import your notebook.  A convenient shortand for this is to define 
-early on::
-
-  script = __name__ == '__main__'
-
-Then in any cell that you need to protect, use::
-
-  if script:
-    # rest of the cell...
-
-
-
 .. _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