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

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

Readme updates
Jonathan Frederic -
Show More
Show file before | Show file after | Hide comments
@@ -1,28 +1,33 b''
1 ================================================================
1 ================================================================
2 nbconvert: conversion utilities for the IPython notebook format
2 NbConvert: Conversion utilities for the IPython notebook format
3 ================================================================
3 ================================================================
4
5
4
6
5 Overview
7 Overview
6 ========
8 ========
7
9
8 nbconvert provides command line utilities to convert to and from IPython
10 NbConvert provides a command line interface to convert to and from IPython
9 notebooks and standard formats.
11 notebooks and standard formats.
10
12
11 - ReST
13 - ReST
12 - Markdown
14 - Markdown
13 - HTML
15 - HTML
14 - Python script
16 - Python script
15 - LaTeX (through Sphinx)
17 - Reveal
18 - LaTeX
19 - Sphinx
16
20
17 As these tools mature, these utilities will be merged into IPython.
21 As these functions mature, they will be merged into IPython.
22
23
18
24
19 Requirements
25 Requirements
20 ============
26 ============
21
27
22 Jinja2
28 Jinja2
23 ~~~~~~
29 ~~~~~~
24
30 All of the exporters rely on the Jinja2 templating language.
25 Most of the converters should rely on the Jinja2 templating language.
26
31
27
32
28 Markdown
33 Markdown
@@ -32,53 +37,30 b' You will need the `python markdown module'
32
37
33
38
34 $ pip install markdown
39 $ pip install markdown
40
35
41
36 Docutils
42 Docutils
37 ~~~~~~~~
43 ~~~~~~~~
38
39 nbconvert requires the latest development version of docutils. This can be installed
44 nbconvert requires the latest development version of docutils. This can be installed
40 via ::
45 via ::
41
46
42 $ curl http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar > docutils.tgz
47 $ curl http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar > docutils.tgz
43 $ pip install -U docutils.tgz
48 $ pip install -U docutils.tgz
49
44
50
45 Sphinx-Latex
51 Sphinx-Latex
46 ~~~~~~~~~~~~
52 ~~~~~~~~~~~~
47
48 We are trying to require as little as possible, but for now, compiling the generated Tex file requires texlive-full.
53 We are trying to require as little as possible, but for now, compiling the generated Tex file requires texlive-full.
49 ::
54 ::
50
55
51 sudo apt-get install texlive-full
56 sudo apt-get install texlive-full
52
57
53
58
54 See http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html
59 *See http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html for more information*
55
56
57 Testing for Sphinx Latex
58 ~~~~~~~~~~~~~~~~~~~~~~~~
59
60 To test, I place a Test1.ipynb file in my nbconvert directory.
61 Then I run this shell script
62
63 ::
64
65 mkdir Test1_files
66 rm Test1_files/*
67
68 python nbconvert2.py latex_sphinx_howto Test1.ipynb
69 mv Test1.tex Test1_files/Test1.tex
70 cd Test1_files
71 pdflatex Test1.tex
72
73 This script will build a Sphinx-howto out of the Test1 IPython notebook.
74 Replace "howto" with "manual" to build a manual.
75
76 Tested against
77 https://github.com/unpingco/Python-for-Signal-Processing
78
60
61
79 Pandoc
62 Pandoc
80 ~~~~~~
63 ~~~~~~
81
82 Nbconvert also needs the `pandoc multiformat converter
64 Nbconvert also needs the `pandoc multiformat converter
83 <http://johnmacfarlane.net/pandoc>`_ to do the actual text conversions. Pandoc
65 <http://johnmacfarlane.net/pandoc>`_ to do the actual text conversions. Pandoc
84 is included in most Linux distribution's package managers, and the author's
66 is included in most Linux distribution's package managers, and the author's
@@ -88,6 +70,7 b' Pandoc, to convert markdown into latex'
88 ::
70 ::
89
71
90 sudo apt-get install pandoc
72 sudo apt-get install pandoc
73
91
74
92 Pygment
75 Pygment
93 ~~~~~~~
76 ~~~~~~~
@@ -96,10 +79,10 b' For conversion to HTML/LaTeX, pygments is also required for syntax highlighting'
96
79
97 $ pip install pygments
80 $ pip install pygments
98
81
99
82
100
83
101 Running Tests
84 Running Tests
102 =============
85 =============
103
86
104 Please try to run the tests to avoid regression when committing a patch, and create new tests when adding features.
87 Please try to run the tests to avoid regression when committing a patch, and create new tests when adding features.
105 ::
88 ::
@@ -107,18 +90,19 b' Please try to run the tests to avoid regression when committing a patch, and cre'
107 $ pip install nose
90 $ pip install nose
108 $ nosetests
91 $ nosetests
109
92
110
93
94
111 Using nbconvert
95 Using nbconvert
112 ===============
96 ===============
113
97
114 You will need to either put the source repository in your ``$PATH`` or symlink
98 You will need to either put the source repository in your ``$PATH`` or symlink
115 the ``nbconvert2.py`` script to a directory in your ``$PATH``, e.g.::
99 the ``nbconvert.py`` script to a directory in your ``$PATH``, e.g.::
116
100
117 $ ln -s /usr/local/bin/nbconvert "$PWD/nbconvert2.py"
101 $ ln -s /usr/local/bin/nbconvert "$PWD/nbconvert.py"
118
102
119 Once this is done, you can call it as::
103 Once this is done, you can call it as::
120
104
121 $ nbconvert <FORMAT> notebook.ipynb > converted.fmt
105 $ nbconvert <FORMAT> notebook.ipynb
122
106
123 Use ``nbconvert -h`` for up to date help on the available formats.
107 Use ``nbconvert -h`` for up to date help on the available formats.
124
108
General Comments 0
You need to be logged in to leave comments. Login now