##// END OF EJS Templates
update nbconvert doc...
MinRK -
Show More
@@ -10,65 +10,66 b' allows you to convert an ``.ipynb`` notebook document file into various static'
10 formats.
10 formats.
11
11
12 Currently, ``nbconvert`` is provided as a command line tool, run as a script
12 Currently, ``nbconvert`` is provided as a command line tool, run as a script
13 using IPython. In the future, a direct export capability from within the
13 using IPython. A direct export capability from within the
14 IPython Notebook web app is planned.
14 IPython Notebook web app is planned.
15
15
16 The command-line syntax to run the ``nbconvert`` script is::
16 The command-line syntax to run the ``nbconvert`` script is::
17
17
18 $ ipython nbconvert --format=FORMAT notebook.ipynb
18 $ ipython nbconvert --to FORMAT notebook.ipynb
19
19
20 This will convert the IPython document file ``notebook.ipynb`` into the output
20 This will convert the IPython document file ``notebook.ipynb`` into the output
21 format given by the ``FORMAT`` string.
21 format given by the ``FORMAT`` string.
22
22
23 The default output format is HTML, for which the ``--format`` modifier may be
23 The default output format is html, for which the ``--to`` argument may be
24 omitted::
24 omitted::
25
25
26 $ ipython nbconvert notebook.ipynb
26 $ ipython nbconvert notebook.ipynb
27
27
28 The currently supported export formats are the following:
28 IPython provides a few templates for some output formats, and these can be
29 specified via an additional ``--template`` argument.
29
30
30 * HTML:
31 The currently supported export formats are:
31
32
32 - **full_html**:
33 * ``--to html``
33 Standard HTML
34
34
35 - **simple_html**:
35 - ``--template full`` (default)
36 Simplified HTML
36 A full static HTML render of the notebook.
37 This looks very similar to the interactive view.
37
38
38 - **reveal**:
39 - ``--template basic``
39 HTML slideshow presentation for use with the ``reveal.js`` package
40 Simplified HTML, useful for embedding in webpages, blogs, etc.
41 This excludes HTML headers.
40
42
41 * PDF:
43 * ``--to latex``
44 Latex export. This generates ``NOTEBOOK_NAME.tex`` file,
45 ready for export. You can automatically run latex on it to generate a PDF
46 by adding ``--post PDF``.
42
47
43 - **sphinx_howto**:
48 - ``--template article`` (default)
44 The format for Sphinx_ HOWTOs; similar to an ``article`` in LaTeX
49 Latex article, derived from Sphinx's howto template.
45
50
46 - **sphinx_manual**:
51 - ``--template book``
47 The format for Sphinx_ manuals; similar to a ``book`` in LaTeX
52 Latex book, derived from Sphinx's manual template.
48
53
49 - **latex**:
54 - ``--template basic``
50 An article formatted completely using LaTeX
55 Very basic latex output - mainly meant as a starting point for custom templates.
51
56
52 * Markup:
57 * ``--to slides``
53
58
54 - **rst**:
59 This generates a Reveal.js HTML slideshow.
55 reStructuredText_ markup
60 It must be served by an HTTP server. The easiest way to get this is to add
61 ``--post serve`` on the command-line.
56
62
57 - **markdown**:
63 * ``--to markdown`` Simple markdown
58 Markdown_ markup
59
64
60 .. _Sphinx: http://sphinx-doc.org/
65 * ``--to rst`` reStructuredText
61 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
62 .. _Markdown: http://daringfireball.net/projects/markdown/syntax
63
66
64 * Python:
67 * ``--to python`` Convert a notebook to an executable Python script.
68 This is the simplest way to get a Python script out of a notebook.
69 If there were any magics in the notebook, this may only be executable from
70 an IPython session.
65
71
66 Comments out all the non-Python code to produce a ``.py`` Python
72 The output file created by ``nbconvert`` will have the same base name as
67 script with just the code content. Currently the output includes IPython
68 magics, and so can be run with ``ipython``, after changing the extension
69 of the script to ``.ipy``.
70
71 The files output file created by ``nbconvert`` will have the same base name as
72 the notebook and will be placed in the current working directory. Any
73 the notebook and will be placed in the current working directory. Any
73 supporting files (graphics, etc) will be placed in a new directory with the
74 supporting files (graphics, etc) will be placed in a new directory with the
74 same base name as the notebook, suffixed with ``_files``::
75 same base name as the notebook, suffixed with ``_files``::
@@ -77,23 +78,10 b' same base name as the notebook, suffixed with ``_files``::'
77 $ ls
78 $ ls
78 notebook.ipynb notebook.html notebook_files/
79 notebook.ipynb notebook.html notebook_files/
79
80
80 Each of the options for PDF export produces as an intermediate step a LaTeX
81 For simple single-file output, such as html, markdown, etc.,
81 ``.tex`` file with the same basename as the notebook, as well as individual
82 the output may be sent to standard output with::
82 files for each figure, and ``.text`` files with textual output from running
83 code cells.
84
85 To actually produce the final PDF file, run the following commands::
86
87 $ ipython nbconvert --format=latex notebook.ipynb
88 $ pdflatex notebook
89
83
90 This requires a local installation of LaTeX on your machine.
84 $ ipython nbconvert --to markdown notebook.ipynb --stdout
91 The output is a PDF file ``notebook.pdf``, also placed inside the
92 ``nbconvert_build`` subdirectory.
93
94 Alternatively, the output may be sent to standard output with::
95
96 $ ipython nbconvert notebook.ipynb --stdout
97
85
98 Multiple notebooks can be specified from the command line::
86 Multiple notebooks can be specified from the command line::
99
87
@@ -110,68 +98,11 b' and using the command::'
110 $ ipython nbconvert --config mycfg.py
98 $ ipython nbconvert --config mycfg.py
111
99
112
100
113 Extracting standard Python files from notebooks
114 -----------------------------------------------
115 ``.ipynb`` notebook document files are plain text files which store a
116 representation in JSON format of the contents of a notebook space. As such,
117 they are not valid ``.py`` Python scripts, and so can be neither imported
118 directly with ``import`` in Python, nor run directly as a standard Python
119 script (though both of these are possible with simple workarounds).
120
121
122 To extract the Python code from within a notebook document, the simplest
123 method is to use the ``File | Download as | Python (.py)`` menu item; the
124 resulting ``.py`` script will be downloaded to your browser's default
125 download location.
126
127 An alternative is to pass an argument to the IPython Notebook, from the moment
128 when it is originally started, specifying that whenever it saves an ``.ipynb``
129 notebook document, it should, at the same time, save the corresponding
130 ``.py`` script. To do so, you can execute the following command::
131
132 $ ipython notebook --script
133
134 or you can set this option permanently in your configuration file with::
135
136 c = get_config()
137 c.NotebookManager.save_script=True
138
139 The result is that standard ``.py`` files are also now generated, which
140 can be ``%run``, imported from regular IPython sessions or other notebooks, or
141 executed at the command line, as usual. Since the raw code you have typed is
142 exported, you must avoid using syntax such as IPython magics and other
143 IPython-specific extensions to the language for the files to be able to be
144 successfully imported.
145 .. or you can change the script's extension to ``.ipy`` and run it with::
146 ..
147 .. $ ipython script.ipy
148
149 In normal Python practice, the standard way to differentiate importable code
150 in a Python script from the "executable" part of a script is to use the
151 following idiom at the start of the executable part of the code::
152
153 if __name__ == '__main__'
154
155 # rest of the code...
156
157 Since all cells in the notebook are run as top-level code, you will need to
158 similarly protect *all* cells that you do not want executed when other scripts
159 try to import your notebook. A convenient shortand for this is to define
160 early on::
161
162 script = __name__ == '__main__'
163
164 Then in any cell that you need to protect, use::
165
166 if script:
167 # rest of the cell...
168
169
170
171 .. _notebook_format:
101 .. _notebook_format:
172
102
173 Notebook JSON file format
103 Notebook JSON file format
174 -------------------------
104 -------------------------
105
175 Notebook documents are JSON files with an ``.ipynb`` extension, formatted
106 Notebook documents are JSON files with an ``.ipynb`` extension, formatted
176 as legibly as possible with minimal extra indentation and cell content broken
107 as legibly as possible with minimal extra indentation and cell content broken
177 across lines to make them reasonably friendly to use in version-control
108 across lines to make them reasonably friendly to use in version-control
General Comments 0
You need to be logged in to leave comments. Login now