##// 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 ================================================================
2 NbConvert: Conversion utilities for the IPython notebook format
3 ================================================================
4
5
6
7 Overview
8 ========
9
10 NbConvert provides a command line interface to convert to and from IPython
11 notebooks and standard formats.
12
13 - ReST
14 - Markdown
15 - HTML
16 - Python script
17 - Reveal
18 - LaTeX
19 - Sphinx
20
21 As these functions mature, they will be merged into IPython.
22
23
24
25 Requirements
26 ============
27
28 Jinja2
29 ~~~~~~
30 All of the exporters rely on the Jinja2 templating language.
31
32
33 Markdown
34 ~~~~~~~~
35 You will need the `python markdown module
36 <http://pypi.python.org/pypi/Markdown>`_ ::
37
38
39 $ pip install markdown
40
41
42 Docutils
43 ~~~~~~~~
44 nbconvert requires the latest development version of docutils. This can be installed
45 via ::
46
47 $ curl http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar > docutils.tgz
48 $ pip install -U docutils.tgz
49
50
51 Sphinx-Latex
52 ~~~~~~~~~~~~
53 We are trying to require as little as possible, but for now, compiling the generated Tex file requires texlive-full.
54 ::
55
56 sudo apt-get install texlive-full
57
58
59 *See http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html for more information*
60
61
62 Pandoc
63 ~~~~~~
64 Nbconvert also needs the `pandoc multiformat converter
65 <http://johnmacfarlane.net/pandoc>`_ to do the actual text conversions. Pandoc
66 is included in most Linux distribution's package managers, and the author's
67 website contains links to Mac OS X and Windows installers.
68
69 Pandoc, to convert markdown into latex
70 ::
71
72 sudo apt-get install pandoc
73
74
75 Pygment
76 ~~~~~~~
77 For conversion to HTML/LaTeX, pygments is also required for syntax highlighting
78 ::
79
80 $ pip install pygments
81
82
83
84 Running Tests
1 ================================================================
2 NbConvert: Conversion utilities for the IPython notebook format
3 ================================================================
4
5
6
7 Overview
8 ========
9
10 NbConvert provides a command line interface to convert from IPython
11 notebooks to standard formats.
12
13 - ReST
14 - Markdown
15 - HTML
16 - Python script
17 - Reveal
18 - LaTeX
19 - Sphinx
20
21 As these functions mature, they will be merged into IPython.
22
23
24 Quick Start
25 ===========
26
27 Dependencies
28 ~~~~~~~~~~~~
29
30 To install the necessary dependencies on a **Linux** machine:
31
32 ::
33
34 pip install jinja2
35 pip install markdown
36 curl http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar > docutils.tgz
37 pip install -U docutils.tgz
38 pip install pygments
39 sudo easy_install -U sphinx
40 sudo apt-get install texlive-full
41 sudo apt-get install pandoc
42
43 If you're on a **Mac**, the last two commands are executed in a different manner (since apt-get doesn't exist.)
44
45 ::
46
47 Install PanDoc via the installer http://code.google.com/p/pandoc/downloads/list
48 Install MacTex via the .pkg http://www.tug.org/mactex/
49
50 Exporting
51 ~~~~~~~~~
52
53 Now, to export a notebook you can call
54
55
56 ::
57
58 python nbconvert.py sphinx_howto book.ipynb
59
60 Where **book.ipynb** *is the name of the notebook* you'd like to convert
61 and **sphinx_howto** *is the output template name*. See */nbconvert/templates/* and
62 */nbconvert/templates/sphinx/* for more. NOTE: the template
63 extension should **not** be included in the template name.
64
65
66 This will create a file.ext (converted file) and /book_files/ directory with all of the output figures.
67
68 Latex Only
69 ~~~~~~~~~~
70
71 If you want to compile a PDF from LaTeX output, move the file.tex (conversion results)
72 into the directory with all the figures /book_files/. The You can then run
73
74 ::
75
76 cd book_files
77 PdfLatex file.tex
78
79 Reveal-powered slideshows
80 ~~~~~~~~~~~~~~~~~~~~~~~~~
81
82 If you want to convert a notebook to a reveal-powered slideshow, you have to call
83
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
87 Please try to run the tests to avoid regression when committing a patch, and create new tests when adding features.
88 ::
89
90 $ pip install nose
91 $ nosetests
92
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
105
106 Please try to run the tests to avoid regression when committing a patch, and create new tests when adding features.
107 ::
108
109 $ pip install nose
110 $ nosetests
111
General Comments 0
You need to be logged in to leave comments. Login now