Merge pull request #7878 from minrk/nbconvert-downgrade

add downgrade example to whatsnew

Author: takluyver

docs/source/notebook/nbconvert.rst

@@ -78,18 +78,44 @@ The currently supported export formats are:
   Basic reStructuredText output. Useful as a starting point for embedding notebooks
   in Sphinx docs.
 
-* ``--to python``
+* ``--to script``
 
-  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
+  Convert a notebook to an executable script.
+  This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook.
+  If there were any magics in an IPython notebook, this may only be executable from
   an IPython session.
+
+* ``--to notebook``
+
+  .. versionadded:: 3.0
+  
+  This doesn't convert a notebook to a different format *per se*,
+  instead it allows the running of nbconvert preprocessors on a notebook,
+  and/or conversion to other notebook formats. For example::
+  
+      ipython nbconvert --to notebook --execute mynotebook.ipynb
+  
+  will open the notebook, execute it, capture new output, and save the result in
+  :file:`mynotebook.nbconvert.ipynb`.
+  
+  ::
+  
+      ipython nbconvert --to notebook --nbformat 3 mynotebook
+  
+  will create a copy of :file:`mynotebook.ipynb` in :file:`mynotebook.v3.ipynb`
+  in version 3 of the :ref:`notebook format <nbformat>`.
+  
+  If you want to convert a notebook in-place,
+  you can specify the ouptut file to be the same as the input file::
+  
+      ipython nbconvert --to notebook mynb --output mynb
+  
+  Be careful with that, since it will replace the input file.
 
 .. note::
 
   nbconvert uses pandoc_ to convert between various markup languages,
-  so pandoc is a dependency of most nbconvert transforms,
-  excluding Markdown and Python.
+  so pandoc is a dependency when converting to latex or reStructuredText.
 
 .. _pandoc: http://johnmacfarlane.net/pandoc/
 

docs/source/whatsnew/version3.rst

@@ -217,6 +217,12 @@ Backwards incompatible changes
     to read and write notebook files
     instead of the deprecated :mod:`IPython.nbformat.current` APIs.
 
+  You can downgrade a notebook to v3 via ``nbconvert``::
+  
+      ipython nbconvert --to notebook --nbformat 3 <notebook>
+  
+  which will create :file:`notebook.v3.ipynb`, a copy of the notebook in v3 format.
+
 * :func:`IPython.core.oinspect.getsource` call specification has changed:
 
   * `oname` keyword argument has been added for property source formatting