Show More
@@ -34,6 +34,10 b' if ON_RTD:' | |||
|
34 | 34 | '__file__': fpath, |
|
35 | 35 | '__name__': '__main__', |
|
36 | 36 | }) |
|
37 | else: | |
|
38 | import sphinx_rtd_theme | |
|
39 | html_theme = "sphinx_rtd_theme" | |
|
40 | html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] | |
|
37 | 41 | |
|
38 | 42 | # If your extensions are in another directory, add it here. If the directory |
|
39 | 43 | # is relative to the documentation root, use os.path.abspath to make it |
@@ -148,7 +152,7 b" default_role = 'literal'" | |||
|
148 | 152 | # The style sheet to use for HTML and HTML Help pages. A file of that name |
|
149 | 153 | # must exist either in Sphinx' static/ path, or in one of the custom paths |
|
150 | 154 | # given in html_static_path. |
|
151 | html_style = 'default.css' | |
|
155 | # html_style = 'default.css' | |
|
152 | 156 | html_favicon = 'favicon.ico' |
|
153 | 157 | |
|
154 | 158 | # The name for this set of Sphinx documents. If None, it defaults to |
@@ -91,6 +91,9 b" release is: ``1.3rc1``. Notice that there is no separator between the '3' and" | |||
|
91 | 91 | the 'r'. Check the environment variable `$VERSION` as well. |
|
92 | 92 | |
|
93 | 93 | |
|
94 | Comment remove the `developpement` entry in `whatsnew/index.rst`. TODO, figure | |
|
95 | out how to make that automatic. | |
|
96 | ||
|
94 | 97 | 5. Run the `tools/build_release` script |
|
95 | 98 | --------------------------------------- |
|
96 | 99 | |
@@ -116,7 +119,8 b' Create and push the tag::' | |||
|
116 | 119 | git tag -am "release $VERSION" "$VERSION" |
|
117 | 120 | git push origin --tags |
|
118 | 121 | |
|
119 |
Update release.py back to `x.y-dev` or `x.y-maint`, and |
|
|
122 | Update release.py back to `x.y-dev` or `x.y-maint`, and re-add the | |
|
123 | `developpement` entry in `docs/source/whatsnew/index.rst` and push:: | |
|
120 | 124 | |
|
121 | 125 | git commit -am "back to development" |
|
122 | 126 | git push origin $BRANCH |
@@ -1,3 +1,5 b'' | |||
|
1 | .. _introduction: | |
|
2 | ||
|
1 | 3 | ===================== |
|
2 | 4 | IPython Documentation |
|
3 | 5 | ===================== |
@@ -7,14 +9,81 b' IPython Documentation' | |||
|
7 | 9 | :Release: |release| |
|
8 | 10 | :Date: |today| |
|
9 | 11 | |
|
10 |
Welcome to the official IPython documentation |
|
|
12 | Welcome to the official IPython documentation | |
|
13 | ||
|
14 | IPython provides a rich toolkit to help you make the most out of using Python | |
|
15 | interactively. Its main components are: | |
|
16 | ||
|
17 | * A powerful interactive Python shell | |
|
18 | * A `Jupyter <http://jupyter.org/>`_ kernel to work with Python code in Jupyter | |
|
19 | notebooks and other interactive frontends. | |
|
20 | ||
|
21 | The enhanced interactive Python shells and kernel have the following main | |
|
22 | features: | |
|
23 | ||
|
24 | * Comprehensive object introspection. | |
|
25 | ||
|
26 | * Input history, persistent across sessions. | |
|
27 | ||
|
28 | * Caching of output results during a session with automatically generated | |
|
29 | references. | |
|
30 | ||
|
31 | * Extensible tab completion, with support by default for completion of python | |
|
32 | variables and keywords, filenames and function keywords. | |
|
33 | ||
|
34 | * Extensible system of 'magic' commands for controlling the environment and | |
|
35 | performing many tasks related either to IPython or the operating system. | |
|
36 | ||
|
37 | * A rich configuration system with easy switching between different setups | |
|
38 | (simpler than changing $PYTHONSTARTUP environment variables every time). | |
|
39 | ||
|
40 | * Session logging and reloading. | |
|
41 | ||
|
42 | * Extensible syntax processing for special purpose situations. | |
|
43 | ||
|
44 | * Access to the system shell with user-extensible alias system. | |
|
45 | ||
|
46 | * Easily embeddable in other Python programs and GUIs. | |
|
47 | ||
|
48 | * Integrated access to the pdb debugger and the Python profiler. | |
|
49 | ||
|
50 | ||
|
51 | The Command line interface inherit all the above functionality and posses | |
|
52 | ||
|
53 | * real multiline editting. | |
|
54 | ||
|
55 | * syntax highlighting as you type | |
|
56 | ||
|
57 | * intgration with command line editor for a better workflow. | |
|
58 | ||
|
59 | The kernel also have its share of feature, when used with a compatible frontend | |
|
60 | it allows for: | |
|
61 | ||
|
62 | * rich display system for object allowing to display Html, Images, Latex,Sounds | |
|
63 | Video. | |
|
64 | ||
|
65 | * interactive widgets with the use of the ``ipywigets`` package. | |
|
66 | ||
|
67 | ||
|
68 | This documentation will walk through most of the features of the IPython | |
|
69 | command line and kernel, as well as describe the internals mechanisms in order | |
|
70 | to improve your Python workflow. | |
|
71 | ||
|
72 | You can always find the table of content for this documentation in the left | |
|
73 | sidebar, allowing you to come back on previous section if needed, or skip ahead. | |
|
74 | ||
|
75 | ||
|
76 | The latest development version is always available from IPython's `GitHub | |
|
77 | repository <http://github.com/ipython/ipython>`_. | |
|
78 | ||
|
79 | ||
|
11 | 80 | |
|
12 | Contents | |
|
13 | ======== | |
|
14 | 81 | |
|
15 | 82 | .. toctree:: |
|
16 | 83 | :maxdepth: 1 |
|
84 | :hidden: | |
|
17 | 85 | |
|
86 | self | |
|
18 | 87 | overview |
|
19 | 88 | whatsnew/index |
|
20 | 89 | install/index |
@@ -5,8 +5,56 b' Installation' | |||
|
5 | 5 | ============ |
|
6 | 6 | |
|
7 | 7 | .. toctree:: |
|
8 |
:maxdepth: |
|
|
8 | :maxdepth: 3 | |
|
9 | :hidden: | |
|
10 | ||
|
9 | 11 | |
|
10 | 12 | install |
|
11 | 13 | kernel_install |
|
12 | 14 | |
|
15 | ||
|
16 | ||
|
17 | This sections will guide you into `installing IPython itself <install>`_, and | |
|
18 | installing `kernels for jupyter <kernel_install>`_ if you are working with | |
|
19 | multiple version of Python, or multiple environments. | |
|
20 | ||
|
21 | To know more, head to the next section. | |
|
22 | ||
|
23 | ||
|
24 | Quick install reminder | |
|
25 | ~~~~~~~~~~~~~~~~~~~~~~ | |
|
26 | ||
|
27 | Here is a quick reminder of the various commands needed if you are already | |
|
28 | familiar with IPython and are just searching to refresh your memory: | |
|
29 | ||
|
30 | Install IPython: | |
|
31 | ||
|
32 | .. code-block:: bash | |
|
33 | ||
|
34 | $ pip install ipython | |
|
35 | ||
|
36 | ||
|
37 | Install and register an IPython kernel with Jupyter: | |
|
38 | ||
|
39 | ||
|
40 | .. code-block:: bash | |
|
41 | ||
|
42 | $ python -m pip install ipykernel | |
|
43 | ||
|
44 | $ python -m ipykernel install [--user] [--name <machine-readable-name>] [--display-name <"User Friendly Name">] | |
|
45 | ||
|
46 | for more help see | |
|
47 | ||
|
48 | .. code-block:: bash | |
|
49 | ||
|
50 | $ python -m ipykernel install --help | |
|
51 | ||
|
52 | ||
|
53 | ||
|
54 | .. seealso:: | |
|
55 | ||
|
56 | `Installing Jupyter <http://jupyter.readthedocs.io/en/latest/install.html>`__ | |
|
57 | The Notebook, nbconvert, and many other former pieces of IPython are now | |
|
58 | part of Project Jupyter. | |
|
59 | ||
|
60 |
@@ -1,34 +1,28 b'' | |||
|
1 | IPython requires Python 2.7 or ≥ 3.3. | |
|
1 | Installing IPython | |
|
2 | ================== | |
|
2 | 3 | |
|
3 | .. seealso:: | |
|
4 | 4 | |
|
5 | `Installing Jupyter <http://jupyter.readthedocs.io/en/latest/install.html>`__ | |
|
6 | The Notebook, nbconvert, and many other former pieces of IPython are now | |
|
7 | part of Project Jupyter. | |
|
5 | IPython requires Python 2.7 or ≥ 3.3. | |
|
8 | 6 | |
|
9 | 7 | |
|
10 |
Quick |
|
|
11 | ========== | |
|
8 | Quick Install | |
|
9 | ------------- | |
|
12 | 10 | |
|
13 | If you have :mod:`pip`, | |
|
14 | the quickest way to get up and running with IPython is: | |
|
11 | With ``pip`` already installed : | |
|
15 | 12 | |
|
16 | 13 | .. code-block:: bash |
|
17 | 14 | |
|
18 | 15 | $ pip install ipython |
|
19 | 16 | |
|
20 | To use IPython with notebooks or the Qt console, you should also install | |
|
21 | ``jupyter``. | |
|
17 | This should install IPython as well as all the other dependency required. | |
|
22 | 18 | |
|
23 | To run IPython's test suite, use the :command:`iptest` command: | |
|
24 | ||
|
25 | .. code-block:: bash | |
|
19 | If you try to use IPython with notebooks or the Qt console, you should also install | |
|
20 | ``jupyter``. | |
|
26 | 21 | |
|
27 | $ iptest | |
|
28 | 22 | |
|
29 | 23 | |
|
30 | 24 | Overview |
|
31 | ======== | |
|
25 | -------- | |
|
32 | 26 | |
|
33 | 27 | This document describes in detail the steps required to install IPython. |
|
34 | 28 | For a few quick ways to get started with package managers or full Python distributions, |
@@ -36,10 +30,10 b' see `the install page <http://ipython.org/install.html>`_ of the IPython website' | |||
|
36 | 30 | |
|
37 | 31 | Please let us know if you have problems installing IPython or any of its dependencies. |
|
38 | 32 | |
|
39 |
IPython and most dependencies |
|
|
33 | IPython and most dependencies should be installed via :command:`pip`. | |
|
40 | 34 | In many scenarios, this is the simplest method of installing Python packages. |
|
41 | 35 | More information about :mod:`pip` can be found on |
|
42 |
`its PyPI page <http |
|
|
36 | `its PyPI page <https://pip.pypa.io>`__. | |
|
43 | 37 | |
|
44 | 38 | |
|
45 | 39 | More general information about installing Python packages can be found in |
@@ -47,21 +41,20 b' More general information about installing Python packages can be found in' | |||
|
47 | 41 | |
|
48 | 42 | |
|
49 | 43 | Installing IPython itself |
|
50 | ========================= | |
|
44 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
|
51 | 45 | |
|
52 | Given a properly built Python, the basic interactive IPython shell will work | |
|
53 | with no external dependencies. However, some Python distributions | |
|
54 | (particularly on Windows and OS X), don't come with a working :mod:`readline` | |
|
55 | module. The IPython shell will work without :mod:`readline`, but will lack | |
|
56 | many features that users depend on, such as tab completion and command line | |
|
57 | editing. If you install IPython with :mod:`pip`, | |
|
58 | then the appropriate :mod:`readline` for your platform will be installed. | |
|
59 | See below for details of how to make sure you have a working :mod:`readline`. | |
|
46 | IPython requires several dependencies to work correctly, it is not recommended | |
|
47 | to install IPython and all it's dependencies manually as this can be quite long and trouble some. | |
|
48 | You should likely use the python package manager ``pip`` | |
|
60 | 49 | |
|
61 | 50 | Installation using pip |
|
62 | ---------------------- | |
|
51 | ~~~~~~~~~~~~~~~~~~~~~~ | |
|
52 | ||
|
53 | Make sure you have the latest version of :mod:`pip` ( the Python package | |
|
54 | manager) installed. If you do not, head to `Pip documentation | |
|
55 | <https://pip.pypa.io/en/stable/installing/>`_ and install it first. | |
|
63 | 56 | |
|
64 | If you have :mod:`pip`, the easiest way of getting IPython is: | |
|
57 | The quickest way to get up and running with IPython is to install it with pip: | |
|
65 | 58 | |
|
66 | 59 | .. code-block:: bash |
|
67 | 60 | |
@@ -71,7 +64,7 b" That's it." | |||
|
71 | 64 | |
|
72 | 65 | |
|
73 | 66 | Installation from source |
|
74 | ------------------------ | |
|
67 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
|
75 | 68 | |
|
76 | 69 | If you don't want to use :command:`pip`, or don't have it installed, |
|
77 | 70 | grab the latest stable tarball of IPython `from PyPI |
@@ -83,12 +76,22 b' grab the latest stable tarball of IPython `from PyPI' | |||
|
83 | 76 | $ cd ipython |
|
84 | 77 | $ pip install . |
|
85 | 78 | |
|
79 | Do not invoke ``setup.py`` directly as this can have undesirable consequences for further upgrades. | |
|
80 | Try to also avoid any usage of ``easy_install`` that can have similar undesirable consequences. | |
|
81 | ||
|
86 | 82 | If you are installing to a location (like ``/usr/local``) that requires higher |
|
87 | permissions, you may need to run the last command with :command:`sudo`. | |
|
83 | permissions, you may need to run the last command with :command:`sudo`. You can | |
|
84 | also install in user specific location by using the ``--user`` flag in conjunction with pip | |
|
85 | ||
|
86 | To can run IPython's test suite, use the :command:`iptest` command from outside of the IPython source tree: | |
|
87 | ||
|
88 | .. code-block:: bash | |
|
89 | ||
|
90 | $ iptest | |
|
88 | 91 |
|
|
89 | 92 |
|
|
90 | 93 | Installing the development version |
|
91 | ---------------------------------- | |
|
94 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
|
92 | 95 | |
|
93 | 96 | It is also possible to install the development version of IPython from our |
|
94 | 97 | `Git <http://git-scm.com/>`_ source code repository. To do this you will |
@@ -100,15 +103,15 b' need to have Git installed on your system. Then do:' | |||
|
100 | 103 | $ cd ipython |
|
101 | 104 | $ pip install . |
|
102 | 105 | |
|
103 |
Some users want to be able to follow the development branch as it changes. |
|
|
104 |
|
|
|
106 | Some users want to be able to follow the development branch as it changes. | |
|
107 | With :mod:`pip` installed, you can replace the last step by: | |
|
105 | 108 | |
|
106 | 109 | .. code-block:: bash |
|
107 | 110 | |
|
108 | 111 | $ pip install -e . |
|
109 | 112 | |
|
110 | 113 | This creates links in the right places and installs the command line script to |
|
111 |
the appropriate |
|
|
114 | the appropriate location. | |
|
112 | 115 | |
|
113 | 116 | Then, if you want to update your IPython at any time, do: |
|
114 | 117 | |
@@ -119,62 +122,10 b' Then, if you want to update your IPython at any time, do:' | |||
|
119 | 122 | .. _dependencies: |
|
120 | 123 | |
|
121 | 124 | Dependencies |
|
122 | ============ | |
|
125 | ~~~~~~~~~~~~ | |
|
123 | 126 | |
|
124 | 127 | IPython relies on a number of other Python packages. Installing using a package |
|
125 | 128 | manager like pip or conda will ensure the necessary packages are installed. If |
|
126 | 129 | you install manually, it's up to you to make sure dependencies are installed. |
|
127 |
They're not listed here, because they may change from release to release, |
|
|
128 | static list will inevitably get out of date. | |
|
129 | ||
|
130 | It also has one key non-Python dependency which you may need to install separately. | |
|
131 | ||
|
132 | readline | |
|
133 | -------- | |
|
134 | ||
|
135 | IPython's terminal interface relies on readline to provide features like tab | |
|
136 | completion and history navigation. If you only want to use IPython as a kernel | |
|
137 | for Jupyter notebooks and other frontends, you don't need readline. | |
|
138 | ||
|
139 | ||
|
140 | **On Windows**, to get full console functionality, *PyReadline* is required. | |
|
141 | PyReadline is a separate, Windows only implementation of readline that uses | |
|
142 | native Windows calls through :mod:`ctypes`. The easiest way of installing | |
|
143 | PyReadline is you use the binary installer available `here | |
|
144 | <http://pypi.python.org/pypi/pyreadline>`__. | |
|
145 | ||
|
146 | **On OS X**, if you are using the built-in Python shipped by Apple, you will be | |
|
147 | missing a proper readline implementation as Apple ships instead a library called | |
|
148 | ``libedit`` that provides only some of readline's functionality. While you may | |
|
149 | find libedit sufficient, we have occasional reports of bugs with it and several | |
|
150 | developers who use OS X as their main environment consider libedit unacceptable | |
|
151 | for productive, regular use with IPython. | |
|
152 | ||
|
153 | Therefore, IPython on OS X depends on the :mod:`gnureadline` module. | |
|
154 | We will *not* consider completion/history problems to be bugs for IPython if you | |
|
155 | are using libedit. | |
|
156 | ||
|
157 | To get a working :mod:`readline` module on OS X, do (with :mod:`pip` | |
|
158 | installed): | |
|
159 | ||
|
160 | .. code-block:: bash | |
|
161 | ||
|
162 | $ pip install gnureadline | |
|
163 | ||
|
164 | .. note:: | |
|
165 | ||
|
166 | Other Python distributions on OS X (such as Anaconda, fink, MacPorts) | |
|
167 | already have proper readline so you likely don't have to do this step. | |
|
168 | ||
|
169 | When IPython is installed with :mod:`pip`, | |
|
170 | the correct readline should be installed if you specify the `terminal` | |
|
171 | optional dependencies: | |
|
172 | ||
|
173 | .. code-block:: bash | |
|
174 | ||
|
175 | $ pip install "ipython[terminal]" | |
|
176 | ||
|
177 | **On Linux**, readline is normally installed by default. If not, install it | |
|
178 | from your system package manager. If you are compiling your own Python, make | |
|
179 | sure you install the readline development headers first. | |
|
180 | ||
|
130 | They're not listed here, because they may change from release to release, and | |
|
131 | depending on platform so a static list will inevitably get out of date. |
@@ -1,9 +1,6 b'' | |||
|
1 | 1 | .. _overview: |
|
2 | 2 | |
|
3 |
======== |
|
|
4 | Introduction | |
|
5 | ============ | |
|
6 | ||
|
3 | ======== | |
|
7 | 4 | Overview |
|
8 | 5 | ======== |
|
9 | 6 | |
@@ -18,10 +15,13 b' interactive and exploratory computing. To support this goal, IPython' | |||
|
18 | 15 | has three main components: |
|
19 | 16 | |
|
20 | 17 | * An enhanced interactive Python shell. |
|
18 | ||
|
21 | 19 | * A decoupled :ref:`two-process communication model <ipythonzmq>`, which |
|
22 | 20 | allows for multiple clients to connect to a computation kernel, most notably |
|
23 | the web-based notebook. | |
|
24 | * An architecture for interactive parallel computing. | |
|
21 | the web-based notebook provided with `Jupyter <https://jupyter.org>`_. | |
|
22 | ||
|
23 | * An architecture for interactive parallel computing now part of the | |
|
24 | `ipyparallel` package. | |
|
25 | 25 | |
|
26 | 26 | All of IPython is open source (released under the revised BSD license). |
|
27 | 27 | |
@@ -69,8 +69,7 b' Main features of the interactive shell' | |||
|
69 | 69 | |
|
70 | 70 | * Completion in the local namespace, by typing :kbd:`TAB` at the prompt. |
|
71 | 71 | This works for keywords, modules, methods, variables and files in the |
|
72 |
current directory. This is supported via the |
|
|
73 | full access to configuring readline's behavior is provided. | |
|
72 | current directory. This is supported via the ``prompt_toolkit`` library. | |
|
74 | 73 | Custom completers can be implemented easily for different purposes |
|
75 | 74 | (system commands, magic arguments etc.) |
|
76 | 75 | |
@@ -79,7 +78,7 b' Main features of the interactive shell' | |||
|
79 | 78 | history and caching of all input and output. |
|
80 | 79 | |
|
81 | 80 | * User-extensible 'magic' commands. A set of commands prefixed with |
|
82 | :samp:`%` is available for controlling IPython itself and provides | |
|
81 | :samp:`%` or :samp:`%%` is available for controlling IPython itself and provides | |
|
83 | 82 | directory control, namespace information and many aliases to |
|
84 | 83 | common system shell commands. |
|
85 | 84 | |
@@ -102,8 +101,8 b' Main features of the interactive shell' | |||
|
102 | 101 | allows you to save arbitrary Python variables. These get restored |
|
103 | 102 | when you run the :samp:`%store -r` command. |
|
104 | 103 | |
|
105 |
* Automatic indentation |
|
|
106 |
|
|
|
104 | * Automatic indentation and highlighting of code as you type (through the | |
|
105 | `prompt_toolkit` library). | |
|
107 | 106 | |
|
108 | 107 | * Macro system for quickly re-executing multiple lines of previous |
|
109 | 108 | input with a single name via the :samp:`%macro` command. Macros can be |
@@ -204,10 +203,11 b' This decoupling allows us to have several clients connected to the same' | |||
|
204 | 203 | kernel, and even allows clients and kernels to live on different machines. |
|
205 | 204 | With the exclusion of the traditional single process terminal-based IPython |
|
206 | 205 | (what you start if you run ``ipython`` without any subcommands), all |
|
207 |
other IPython machinery uses this two-process model. |
|
|
208 | console``, ``ipython qtconsole``, and ``ipython notebook``. | |
|
206 | other IPython machinery uses this two-process model. Most of this is now part | |
|
207 | of the `Jupyter` project, whis includes ``jupyter console``, ``jupyter | |
|
208 | qtconsole``, and ``jupyter notebook``. | |
|
209 | 209 | |
|
210 |
As an example, this means that when you start `` |
|
|
210 | As an example, this means that when you start ``jupyter qtconsole``, you're | |
|
211 | 211 | really starting two processes, a kernel and a Qt-based client can send |
|
212 | 212 | commands to and receive results from that kernel. If there is already a kernel |
|
213 | 213 | running that you want to connect to, you can pass the ``--existing`` flag |
@@ -217,7 +217,7 b' running, use the ``%connect_info`` magic to get the unique connection file,' | |||
|
217 | 217 | which will be something like ``--existing kernel-19732.json`` but with |
|
218 | 218 | different numbers which correspond to the Process ID of the kernel. |
|
219 | 219 | |
|
220 |
You can read more about using ` |
|
|
220 | You can read more about using `jupyter qtconsole | |
|
221 | 221 | <http://jupyter.org/qtconsole/>`_, and |
|
222 | 222 | `ipython notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`_. There |
|
223 | 223 | is also a :ref:`message spec <messaging>` which documents the protocol for |
@@ -232,6 +232,11 b' and clients.' | |||
|
232 | 232 | Interactive parallel computing |
|
233 | 233 | ============================== |
|
234 | 234 | |
|
235 | .. note:: | |
|
236 | ||
|
237 | This functionality is optional and now part of the `ipyparallel | |
|
238 | <http://ipyparallel.readthedocs.io/>`_ project. | |
|
239 | ||
|
235 | 240 | Increasingly, parallel computer hardware, such as multicore CPUs, clusters and |
|
236 | 241 | supercomputers, is becoming ubiquitous. Over the last several years, we have |
|
237 | 242 | developed an architecture within IPython that allows such hardware to be used |
@@ -20,8 +20,8 b' development work they do here in a user friendly format.' | |||
|
20 | 20 | .. toctree:: |
|
21 | 21 | :maxdepth: 1 |
|
22 | 22 | |
|
23 | version5 | |
|
24 | 23 | development |
|
24 | version5 | |
|
25 | 25 | version4 |
|
26 | 26 | github-stats-4 |
|
27 | 27 | version3 |
|
1 | NO CONTENT: file was removed | |
This diff has been collapsed as it changes many lines, (534 lines changed) Show them Hide them |
|
1 | NO CONTENT: file was removed |
General Comments 0
You need to be logged in to leave comments.
Login now