##// END OF EJS Templates
Describe nbconvert in architecture doc
Thomas Kluyver -
Show More
1 NO CONTENT: new file 100644, binary diff hidden
@@ -0,0 +1,195 b''
1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!-- Created with Inkscape (http://www.inkscape.org/) -->
3
4 <svg
5 xmlns:dc="http://purl.org/dc/elements/1.1/"
6 xmlns:cc="http://creativecommons.org/ns#"
7 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
8 xmlns:svg="http://www.w3.org/2000/svg"
9 xmlns="http://www.w3.org/2000/svg"
10 xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
11 xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
12 width="738.99115"
13 height="392.50452"
14 id="svg2"
15 version="1.1"
16 inkscape:version="0.48.5 r10040"
17 sodipodi:docname="nbconvert.svg"
18 inkscape:export-filename="/home/takluyver/Code/ipython/docs/source/development/figs/nbconvert.png"
19 inkscape:export-xdpi="80.024559"
20 inkscape:export-ydpi="80.024559">
21 <defs
22 id="defs4" />
23 <sodipodi:namedview
24 id="base"
25 pagecolor="#ffffff"
26 bordercolor="#666666"
27 borderopacity="1.0"
28 inkscape:pageopacity="0.0"
29 inkscape:pageshadow="2"
30 inkscape:zoom="0.98994949"
31 inkscape:cx="258.16627"
32 inkscape:cy="42.987401"
33 inkscape:document-units="px"
34 inkscape:current-layer="layer1"
35 showgrid="false"
36 inkscape:window-width="1680"
37 inkscape:window-height="1014"
38 inkscape:window-x="0"
39 inkscape:window-y="0"
40 inkscape:window-maximized="1"
41 fit-margin-top="1"
42 fit-margin-left="1"
43 fit-margin-right="1"
44 fit-margin-bottom="1"
45 units="cm" />
46 <metadata
47 id="metadata7">
48 <rdf:RDF>
49 <cc:Work
50 rdf:about="">
51 <dc:format>image/svg+xml</dc:format>
52 <dc:type
53 rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
54 <dc:title></dc:title>
55 </cc:Work>
56 </rdf:RDF>
57 </metadata>
58 <g
59 inkscape:label="Layer 1"
60 inkscape:groupmode="layer"
61 id="layer1"
62 transform="translate(6.8705709,12.370571)">
63 <rect
64 style="fill:#ffeeaa;fill-opacity:1;stroke:#000000;stroke-width:3.07408524;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
65 id="rect2987"
66 width="136.5"
67 height="77.142876"
68 x="186.57104"
69 y="59.505043"
70 ry="17.142857" />
71 <g
72 id="g3951"
73 transform="translate(0,-380)">
74 <path
75 sodipodi:nodetypes="cccccc"
76 inkscape:connector-curvature="0"
77 id="rect2993"
78 d="m 29.807988,404.31302 78.763442,0 18.76344,18.76345 0,128.76344 -97.526882,0 z"
79 style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:2.47311282;stroke-miterlimit:4;stroke-opacity:1" />
80 <text
81 transform="matrix(0,-1,1,0,0,0)"
82 sodipodi:linespacing="125%"
83 id="text2996"
84 y="89.071426"
85 x="-541.26105"
86 style="font-size:28px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Droid Sans;-inkscape-font-specification:Droid Sans"
87 xml:space="preserve"><tspan
88 y="89.071426"
89 x="-541.26105"
90 id="tspan2998"
91 sodipodi:role="line">Notebook</tspan></text>
92 </g>
93 <text
94 xml:space="preserve"
95 style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Droid Sans;-inkscape-font-specification:Droid Sans"
96 x="190.29956"
97 y="102.81281"
98 id="text3771"
99 sodipodi:linespacing="125%"><tspan
100 sodipodi:role="line"
101 id="tspan3773"
102 x="190.29956"
103 y="102.81281">Preprocessors</tspan></text>
104 <path
105 style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.33420539;stroke-miterlimit:4;stroke-opacity:1"
106 d="m 127.2381,90.36977 43.55684,0 0,-7.7067 13.61068,15.4134 -13.61068,15.41339 0,-7.7067 -43.55684,0 z"
107 id="rect3768"
108 inkscape:connector-curvature="0"
109 sodipodi:nodetypes="cccccccc" />
110 <rect
111 style="fill:#ffeeaa;fill-opacity:1;stroke:#000000;stroke-width:3.07408524;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
112 id="rect2987-2"
113 width="136.5"
114 height="77.142876"
115 x="382.36203"
116 y="59.505249"
117 ry="17.142857" />
118 <text
119 xml:space="preserve"
120 style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Droid Sans;-inkscape-font-specification:Droid Sans"
121 x="411.20285"
122 y="102.81302"
123 id="text3771-7"
124 sodipodi:linespacing="125%"><tspan
125 sodipodi:role="line"
126 id="tspan3773-0"
127 x="411.20285"
128 y="102.81302">Exporter</tspan></text>
129 <path
130 style="fill:none;stroke:#000000;stroke-width:1.33420539;stroke-miterlimit:4;stroke-opacity:1"
131 d="m 322.9901,90.36977 43.55684,0 0,-7.7067 13.61068,15.4134 -13.61068,15.41339 0,-7.7067 -43.55684,0 z"
132 id="rect3768-2"
133 inkscape:connector-curvature="0"
134 sodipodi:nodetypes="cccccccc" />
135 <path
136 style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.33420539;stroke-miterlimit:4;stroke-opacity:1"
137 d="m 499.2791,261.98048 43.55684,0 0,-7.7067 13.61068,15.4134 -13.61068,15.41339 0,-7.7067 -43.55684,0 z"
138 id="rect3768-2-9"
139 inkscape:connector-curvature="0"
140 sodipodi:nodetypes="cccccccc" />
141 <path
142 style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.33420539;stroke-miterlimit:4;stroke-opacity:1"
143 d="m 458.31874,136.85255 0,43.55684 7.7067,0 -15.4134,13.61069 -15.41339,-13.61069 7.70669,0 0,-43.55684 z"
144 id="rect3768-2-6"
145 inkscape:connector-curvature="0"
146 sodipodi:nodetypes="cccccccc" />
147 <g
148 id="g3882"
149 transform="translate(-25.169808,-387.70536)">
150 <path
151 sodipodi:nodetypes="cccccc"
152 inkscape:connector-curvature="0"
153 id="rect2993-4"
154 d="m 427.01841,583.62909 78.76344,0 18.76344,18.76345 0,128.76345 -97.52688,0 z"
155 style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:2.47311282;stroke-miterlimit:4;stroke-opacity:1" />
156 <text
157 transform="matrix(0,-1,1,0,0,0)"
158 sodipodi:linespacing="125%"
159 id="text3876"
160 y="467.78186"
161 x="-657.84564"
162 style="font-size:32px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Droid Sans;-inkscape-font-specification:Droid Sans"
163 xml:space="preserve"><tspan
164 y="467.78186"
165 x="-657.84564"
166 id="tspan3878"
167 sodipodi:role="line"
168 style="font-size:28px">Exported</tspan><tspan
169 id="tspan3880"
170 y="502.78186"
171 x="-657.84564"
172 sodipodi:role="line"
173 style="font-size:28px">file</tspan></text>
174 </g>
175 <rect
176 style="fill:#ffeeaa;fill-opacity:1;stroke:#000000;stroke-width:3.07408524;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
177 id="rect2987-1"
178 width="136.5"
179 height="77.142876"
180 x="558.65106"
181 y="231.11572"
182 ry="17.142857" />
183 <text
184 xml:space="preserve"
185 style="font-size:19px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Droid Sans;-inkscape-font-specification:Droid Sans"
186 x="561.46796"
187 y="274.42346"
188 id="text3771-0"
189 sodipodi:linespacing="125%"><tspan
190 sodipodi:role="line"
191 id="tspan3773-5"
192 x="561.46796"
193 y="274.42346">Postprocessors</tspan></text>
194 </g>
195 </svg>
@@ -1,71 +1,89 b''
1 1 How IPython Works
2 2 =================
3 3
4 4 Terminal IPython
5 5 ----------------
6 6
7 7 When you type ``ipython``, you get the original IPython interface, running in
8 8 the terminal. It does something like this::
9 9
10 10 while True:
11 11 code = input(">>> ")
12 12 exec(code)
13 13
14 14 Of course, it's much more complicated, because it has to deal with multi-line
15 15 code, tab completion using :mod:`readline`, magic commands, and so on. But the
16 16 model is like that: prompt the user for some code, and when they've entered it,
17 17 exec it in the same process.
18 18
19 19 The IPython Kernel
20 20 ------------------
21 21
22 22 All the other interfaces—the Notebook, the Qt console, ``ipython console`` in
23 23 the terminal, and third party interfaces—use the IPython Kernel. This is a
24 24 separate process which is responsible for running user code, and things like
25 25 computing possible completions. Frontends communicate with it using JSON
26 26 messages sent over ZeroMQ sockets; the protocol they use is described in
27 27 :doc:`messaging`.
28 28
29 29 The core execution machinery for the kernel is shared with terminal IPython:
30 30
31 31 .. image:: figs/ipy_kernel_and_terminal.png
32 32
33 33 A kernel process can be connected to more than one frontend simultaneously. In
34 34 this case, the different frontends will have access to the same variables.
35 35
36 36 .. TODO: Diagram illustrating this?
37 37
38 38 This design was intended to allow easy development of different frontends based
39 39 on the same kernel, but it also made it possible to support new languages in the
40 40 same frontends, by developing kernels in those languages, and we are refining
41 41 IPython to make that more practical.
42 42
43 43 Today, there are two ways to develop a kernel for another language. Wrapper
44 44 kernels reuse the communications machinery from IPython, and implement only the
45 45 core execution part. Native kernels implement execution and communications in
46 46 the target language:
47 47
48 48 .. image:: figs/other_kernels.png
49 49
50 50 .. seealso::
51 51
52 52 :doc:`kernels`
53 53
54 54 :doc:`wrapperkernels`
55 55
56 56 Notebooks
57 57 ---------
58 58
59 59 The Notebook frontend does something extra. In addition to running your code, it
60 60 stores code and output, together with markdown notes, in an editable document
61 61 called a notebook. When you save it, this is sent from your browser to the
62 62 notebook server, which saves it on disk as a JSON file with a ``.ipynb``
63 63 extension.
64 64
65 65 .. TODO: Diagram of how these pieces fit together.
66 66
67 67 The notebook server, not the kernel, is responsible for saving and loading
68 68 notebooks, so you can edit notebooks even if you don't have the kernel for that
69 69 language—you just won't be able to run code. The kernel doesn't know anything
70 70 about the notebook document: it just gets sent cells of code to execute when the
71 71 user runs them.
72
73 Exporting to other formats
74 ``````````````````````````
75
76 The Nbconvert tool in IPython converts notebook files to other formats, such as
77 HTML, LaTeX, or reStructuredText. This conversion goes through a series of steps:
78
79 .. image:: figs/nbconvert.png
80
81 1. Preprocessors modify the notebook in memory. E.g. ExecutePreprocessor runs
82 the code in the notebook and updates the output.
83 2. An exporter converts the notebook to another file format. Most of the
84 exporters use templates for this.
85 3. Postprocessors work on the file produced by exporting.
86
87 The `nbviewer <http://nbviewer.ipython.org/>`_ website uses nbconvert with the
88 HTML exporter. When you give it a URL, it fetches the notebook from that URL,
89 converts it to HTML, and serves that HTML to you.
@@ -1,31 +1,32 b''
1 1 .. _developer_guide:
2 2
3 3 =========================
4 4 IPython developer's guide
5 5 =========================
6 6
7 7 This are two categories of developer focused documentation:
8 8
9 9 1. Documentation for developers of *IPython itself*.
10 10 2. Documentation for developers of third party tools and libraries
11 11 that use IPython.
12 12
13 13 This part of our documentation only contains information in the second category.
14 14
15 15 Developers interested in working on IPython itself should consult
16 16 our `developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_
17 17 on the IPython GitHub wiki.
18 18
19 19 .. toctree::
20 20 :maxdepth: 1
21 21
22 how_ipython_works
22 23 messaging
23 24 kernels
24 25 wrapperkernels
25 26 execution
26 27 parallel_messages
27 28 parallel_connections
28 29 lexer
29 30 pycompat
30 31 config
31 32 inputhook_app
General Comments 0
You need to be logged in to leave comments. Login now