From be3998aa51bddcbdc8e40b26d53eb35776168ff3 2013-07-30 00:13:55 From: MinRK Date: 2013-07-30 00:13:55 Subject: [PATCH] update nbconvert doc update to new CLI remove documentation of ill-advised `--script` option. --- diff --git a/docs/source/interactive/converting_notebooks.rst b/docs/source/interactive/converting_notebooks.rst index a41b441..3bd9a3f 100644 --- a/docs/source/interactive/converting_notebooks.rst +++ b/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**: - Standard HTML +* ``--to html`` - - **simple_html**: - Simplified HTML + - ``--template full`` (default) + A full static HTML render of the notebook. + This looks very similar to the interactive view. - - **reveal**: - HTML slideshow presentation for use with the ``reveal.js`` package + - ``--template basic`` + Simplified HTML, useful for embedding in webpages, blogs, etc. + This excludes HTML headers. -* PDF: - - - **sphinx_howto**: - The format for Sphinx_ HOWTOs; similar to an ``article`` in LaTeX +* ``--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_manual**: - The format for Sphinx_ manuals; similar to a ``book`` in LaTeX + - ``--template book`` + Latex book, derived from Sphinx's manual template. - - **latex**: - An article formatted completely using LaTeX + - ``--template basic`` + Very basic latex output - mainly meant as a starting point for custom templates. -* Markup: +* ``--to slides`` - - **rst**: - reStructuredText_ 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. - - **markdown**: - Markdown_ markup +* ``--to markdown`` Simple markdown -.. _Sphinx: http://sphinx-doc.org/ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Markdown: http://daringfireball.net/projects/markdown/syntax +* ``--to rst`` reStructuredText -* Python: +* ``--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. - 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 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 -``.tex`` file with the same basename as the notebook, as well as individual -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:: +For simple single-file output, such as html, markdown, etc., +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