##// END OF EJS Templates
upstream » ipython
RSS

Clone from https://github.com/ipython/ipython.git

Merge pull request #169 from jdfreder/master...
Matthias Bussonnier -
r10857:34b77601 merge
parent child Browse files
Show More
Show file before | Show file after | Hide comments
@@ -1,108 +1,111 b''
1 ================================================================
1 ================================================================
2 NbConvert: Conversion utilities for the IPython notebook format
2 NbConvert: Conversion utilities for the IPython notebook format
3 ================================================================
3 ================================================================
4
4
5
5
6
6
7 Overview
7 Overview
8 ========
8 ========
9
9
10 NbConvert provides a command line interface to convert to and from IPython
10 NbConvert provides a command line interface to convert from IPython
11 notebooks and standard formats.
11 notebooks to standard formats.
12
12
13 - ReST
13 - ReST
14 - Markdown
14 - Markdown
15 - HTML
15 - HTML
16 - Python script
16 - Python script
17 - Reveal
17 - Reveal
18 - LaTeX
18 - LaTeX
19 - Sphinx
19 - Sphinx
20
20
21 As these functions mature, they will be merged into IPython.
21 As these functions mature, they will be merged into IPython.
22
22
23
23
24
24 Quick Start
25 Requirements
25 ===========
26 ============
26
27
27 Dependencies
28 Jinja2
28 ~~~~~~~~~~~~
29 ~~~~~~
29
30 All of the exporters rely on the Jinja2 templating language.
30 To install the necessary dependencies on a **Linux** machine:
31
31
32
32 ::
33 Markdown
33
34 ~~~~~~~~
34 pip install jinja2
35 You will need the `python markdown module
35 pip install markdown
36 <http://pypi.python.org/pypi/Markdown>`_ ::
36 curl http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar > docutils.tgz
37
37 pip install -U docutils.tgz
38
38 pip install pygments
39 $ pip install markdown
39 sudo easy_install -U sphinx
40
40 sudo apt-get install texlive-full
41
41 sudo apt-get install pandoc
42 Docutils
42
43 ~~~~~~~~
43 If you're on a **Mac**, the last two commands are executed in a different manner (since apt-get doesn't exist.)
44 nbconvert requires the latest development version of docutils. This can be installed
44
45 via ::
45 ::
46
46
47 $ curl http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar > docutils.tgz
47 Install PanDoc via the installer http://code.google.com/p/pandoc/downloads/list
48 $ pip install -U docutils.tgz
48 Install MacTex via the .pkg http://www.tug.org/mactex/
49
49
50
50 Exporting
51 Sphinx-Latex
51 ~~~~~~~~~
52 ~~~~~~~~~~~~
52
53 We are trying to require as little as possible, but for now, compiling the generated Tex file requires texlive-full.
53 Now, to export a notebook you can call
54 ::
54
55
55
56 sudo apt-get install texlive-full
56 ::
57
57
58
58 python nbconvert.py sphinx_howto book.ipynb
59 *See http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html for more information*
59
60
60 Where **book.ipynb** *is the name of the notebook* you'd like to convert
61
61 and **sphinx_howto** *is the output template name*. See */nbconvert/templates/* and
62 Pandoc
62 */nbconvert/templates/sphinx/* for more. NOTE: the template
63 ~~~~~~
63 extension should **not** be included in the template name.
64 Nbconvert also needs the `pandoc multiformat converter
64
65 <http://johnmacfarlane.net/pandoc>`_ to do the actual text conversions. Pandoc
65
66 is included in most Linux distribution's package managers, and the author's
66 This will create a file.ext (converted file) and /book_files/ directory with all of the output figures.
67 website contains links to Mac OS X and Windows installers.
67
68
68 Latex Only
69 Pandoc, to convert markdown into latex
69 ~~~~~~~~~~
70 ::
70
71
71 If you want to compile a PDF from LaTeX output, move the file.tex (conversion results)
72 sudo apt-get install pandoc
72 into the directory with all the figures /book_files/. The You can then run
73
73
74
74 ::
75 Pygment
75
76 ~~~~~~~
76 cd book_files
77 For conversion to HTML/LaTeX, pygments is also required for syntax highlighting
77 PdfLatex file.tex
78 ::
78
79
79 Reveal-powered slideshows
80 $ pip install pygments
80 ~~~~~~~~~~~~~~~~~~~~~~~~~
81
81
82
82 If you want to convert a notebook to a reveal-powered slideshow, you have to call
83
83
84 Running Tests
84 ::
85
86 python nbconvert.py reveal your_slideshow.ipynb
87
88 and then, you will get a your_slideshow.reveal.html file.
89
90 But the slideshow will not be rendered correctly if you do not download and unzip the reveal.js library
91 in the same folder where your_slideshow.reveal.html file is located.
92
93 **Note**: You can get the reveal.js library from this link: https://github.com/hakimel/reveal.js/archive/2.4.0.zip
94
95 Finally, to see the slideshow, just serve it
96
97 ::
98
99 python -m SimpleHTTPServer 8000
100
101 and point your browser to http://localhost:8000.
102
103 Running Tests
85 =============
104 =============
86
105
87 Please try to run the tests to avoid regression when committing a patch, and create new tests when adding features.
106 Please try to run the tests to avoid regression when committing a patch, and create new tests when adding features.
88 ::
107 ::
89
108
90 $ pip install nose
109 $ pip install nose
91 $ nosetests
110 $ nosetests
92
111
93
94
95 Using nbconvert
96 ===============
97
98 You will need to either put the source repository in your ``$PATH`` or symlink
99 the ``nbconvert.py`` script to a directory in your ``$PATH``, e.g.::
100
101 $ ln -s /usr/local/bin/nbconvert "$PWD/nbconvert.py"
102
103 Once this is done, you can call it as::
104
105 $ nbconvert <FORMAT> notebook.ipynb
106
107 Use ``nbconvert -h`` for up to date help on the available formats.
108
General Comments 0
You need to be logged in to leave comments. Login now