##// END OF EJS Templates
Documentation overhaul....
Matthias Bussonnier -
Show More
@@ -34,6 +34,10 b' if ON_RTD:'
34 '__file__': fpath,
34 '__file__': fpath,
35 '__name__': '__main__',
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 # If your extensions are in another directory, add it here. If the directory
42 # If your extensions are in another directory, add it here. If the directory
39 # is relative to the documentation root, use os.path.abspath to make it
43 # is relative to the documentation root, use os.path.abspath to make it
@@ -148,7 +152,7 b" default_role = 'literal'"
148 # The style sheet to use for HTML and HTML Help pages. A file of that name
152 # The style sheet to use for HTML and HTML Help pages. A file of that name
149 # must exist either in Sphinx' static/ path, or in one of the custom paths
153 # must exist either in Sphinx' static/ path, or in one of the custom paths
150 # given in html_static_path.
154 # given in html_static_path.
151 html_style = 'default.css'
155 # html_style = 'default.css'
152 html_favicon = 'favicon.ico'
156 html_favicon = 'favicon.ico'
153
157
154 # The name for this set of Sphinx documents. If None, it defaults to
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 the 'r'. Check the environment variable `$VERSION` as well.
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 5. Run the `tools/build_release` script
97 5. Run the `tools/build_release` script
95 ---------------------------------------
98 ---------------------------------------
96
99
@@ -116,7 +119,8 b' Create and push the tag::'
116 git tag -am "release $VERSION" "$VERSION"
119 git tag -am "release $VERSION" "$VERSION"
117 git push origin --tags
120 git push origin --tags
118
121
119 Update release.py back to `x.y-dev` or `x.y-maint`, and push::
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 git commit -am "back to development"
125 git commit -am "back to development"
122 git push origin $BRANCH
126 git push origin $BRANCH
@@ -1,3 +1,5 b''
1 .. _introduction:
2
1 =====================
3 =====================
2 IPython Documentation
4 IPython Documentation
3 =====================
5 =====================
@@ -7,14 +9,81 b' IPython Documentation'
7 :Release: |release|
9 :Release: |release|
8 :Date: |today|
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 .. toctree::
82 .. toctree::
16 :maxdepth: 1
83 :maxdepth: 1
84 :hidden:
17
85
86 self
18 overview
87 overview
19 whatsnew/index
88 whatsnew/index
20 install/index
89 install/index
@@ -5,8 +5,56 b' Installation'
5 ============
5 ============
6
6
7 .. toctree::
7 .. toctree::
8 :maxdepth: 2
8 :maxdepth: 3
9 :hidden:
10
9
11
10 install
12 install
11 kernel_install
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>`__
5 IPython requires Python 2.7 or ≥ 3.3.
6 The Notebook, nbconvert, and many other former pieces of IPython are now
7 part of Project Jupyter.
8
6
9
7
10 Quickstart
8 Quick Install
11 ==========
9 -------------
12
10
13 If you have :mod:`pip`,
11 With ``pip`` already installed :
14 the quickest way to get up and running with IPython is:
15
12
16 .. code-block:: bash
13 .. code-block:: bash
17
14
18 $ pip install ipython
15 $ pip install ipython
19
16
20 To use IPython with notebooks or the Qt console, you should also install
17 This should install IPython as well as all the other dependency required.
21 ``jupyter``.
22
18
23 To run IPython's test suite, use the :command:`iptest` command:
19 If you try to use IPython with notebooks or the Qt console, you should also install
24
20 ``jupyter``.
25 .. code-block:: bash
26
21
27 $ iptest
28
22
29
23
30 Overview
24 Overview
31 ========
25 --------
32
26
33 This document describes in detail the steps required to install IPython.
27 This document describes in detail the steps required to install IPython.
34 For a few quick ways to get started with package managers or full Python distributions,
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 Please let us know if you have problems installing IPython or any of its dependencies.
31 Please let us know if you have problems installing IPython or any of its dependencies.
38
32
39 IPython and most dependencies can be installed via :command:`pip`.
33 IPython and most dependencies should be installed via :command:`pip`.
40 In many scenarios, this is the simplest method of installing Python packages.
34 In many scenarios, this is the simplest method of installing Python packages.
41 More information about :mod:`pip` can be found on
35 More information about :mod:`pip` can be found on
42 `its PyPI page <http://pypi.python.org/pypi/pip>`__.
36 `its PyPI page <https://pip.pypa.io>`__.
43
37
44
38
45 More general information about installing Python packages can be found in
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 Installing IPython itself
43 Installing IPython itself
50 =========================
44 ~~~~~~~~~~~~~~~~~~~~~~~~~
51
45
52 Given a properly built Python, the basic interactive IPython shell will work
46 IPython requires several dependencies to work correctly, it is not recommended
53 with no external dependencies. However, some Python distributions
47 to install IPython and all it's dependencies manually as this can be quite long and trouble some.
54 (particularly on Windows and OS X), don't come with a working :mod:`readline`
48 You should likely use the python package manager ``pip``
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`.
60
49
61 Installation using pip
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 .. code-block:: bash
59 .. code-block:: bash
67
60
@@ -71,7 +64,7 b" That's it."
71
64
72
65
73 Installation from source
66 Installation from source
74 ------------------------
67 ~~~~~~~~~~~~~~~~~~~~~~~~
75
68
76 If you don't want to use :command:`pip`, or don't have it installed,
69 If you don't want to use :command:`pip`, or don't have it installed,
77 grab the latest stable tarball of IPython `from PyPI
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 $ cd ipython
76 $ cd ipython
84 $ pip install .
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 If you are installing to a location (like ``/usr/local``) that requires higher
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 Installing the development version
93 Installing the development version
91 ----------------------------------
94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
95
93 It is also possible to install the development version of IPython from our
96 It is also possible to install the development version of IPython from our
94 `Git <http://git-scm.com/>`_ source code repository. To do this you will
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 $ cd ipython
103 $ cd ipython
101 $ pip install .
104 $ pip install .
102
105
103 Some users want to be able to follow the development branch as it changes. If
106 Some users want to be able to follow the development branch as it changes.
104 you have :mod:`pip`, you can replace the last step by:
107 With :mod:`pip` installed, you can replace the last step by:
105
108
106 .. code-block:: bash
109 .. code-block:: bash
107
110
108 $ pip install -e .
111 $ pip install -e .
109
112
110 This creates links in the right places and installs the command line script to
113 This creates links in the right places and installs the command line script to
111 the appropriate places.
114 the appropriate location.
112
115
113 Then, if you want to update your IPython at any time, do:
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 .. _dependencies:
122 .. _dependencies:
120
123
121 Dependencies
124 Dependencies
122 ============
125 ~~~~~~~~~~~~
123
126
124 IPython relies on a number of other Python packages. Installing using a package
127 IPython relies on a number of other Python packages. Installing using a package
125 manager like pip or conda will ensure the necessary packages are installed. If
128 manager like pip or conda will ensure the necessary packages are installed. If
126 you install manually, it's up to you to make sure dependencies are installed.
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, so a
130 They're not listed here, because they may change from release to release, and
128 static list will inevitably get out of date.
131 depending on platform so a 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
@@ -1,9 +1,6 b''
1 .. _overview:
1 .. _overview:
2
2
3 ============
3 ========
4 Introduction
5 ============
6
7 Overview
4 Overview
8 ========
5 ========
9
6
@@ -18,10 +15,13 b' interactive and exploratory computing. To support this goal, IPython'
18 has three main components:
15 has three main components:
19
16
20 * An enhanced interactive Python shell.
17 * An enhanced interactive Python shell.
18
21 * A decoupled :ref:`two-process communication model <ipythonzmq>`, which
19 * A decoupled :ref:`two-process communication model <ipythonzmq>`, which
22 allows for multiple clients to connect to a computation kernel, most notably
20 allows for multiple clients to connect to a computation kernel, most notably
23 the web-based notebook.
21 the web-based notebook provided with `Jupyter <https://jupyter.org>`_.
24 * An architecture for interactive parallel computing.
22
23 * An architecture for interactive parallel computing now part of the
24 `ipyparallel` package.
25
25
26 All of IPython is open source (released under the revised BSD license).
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 * Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
70 * Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
71 This works for keywords, modules, methods, variables and files in the
71 This works for keywords, modules, methods, variables and files in the
72 current directory. This is supported via the readline library, and
72 current directory. This is supported via the ``prompt_toolkit`` library.
73 full access to configuring readline's behavior is provided.
74 Custom completers can be implemented easily for different purposes
73 Custom completers can be implemented easily for different purposes
75 (system commands, magic arguments etc.)
74 (system commands, magic arguments etc.)
76
75
@@ -79,7 +78,7 b' Main features of the interactive shell'
79 history and caching of all input and output.
78 history and caching of all input and output.
80
79
81 * User-extensible 'magic' commands. A set of commands prefixed with
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 directory control, namespace information and many aliases to
82 directory control, namespace information and many aliases to
84 common system shell commands.
83 common system shell commands.
85
84
@@ -102,8 +101,8 b' Main features of the interactive shell'
102 allows you to save arbitrary Python variables. These get restored
101 allows you to save arbitrary Python variables. These get restored
103 when you run the :samp:`%store -r` command.
102 when you run the :samp:`%store -r` command.
104
103
105 * Automatic indentation (optional) of code as you type (through the
104 * Automatic indentation and highlighting of code as you type (through the
106 readline library).
105 `prompt_toolkit` library).
107
106
108 * Macro system for quickly re-executing multiple lines of previous
107 * Macro system for quickly re-executing multiple lines of previous
109 input with a single name via the :samp:`%macro` command. Macros can be
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 kernel, and even allows clients and kernels to live on different machines.
203 kernel, and even allows clients and kernels to live on different machines.
205 With the exclusion of the traditional single process terminal-based IPython
204 With the exclusion of the traditional single process terminal-based IPython
206 (what you start if you run ``ipython`` without any subcommands), all
205 (what you start if you run ``ipython`` without any subcommands), all
207 other IPython machinery uses this two-process model. This includes ``ipython
206 other IPython machinery uses this two-process model. Most of this is now part
208 console``, ``ipython qtconsole``, and ``ipython notebook``.
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 ``ipython qtconsole``, you're
210 As an example, this means that when you start ``jupyter qtconsole``, you're
211 really starting two processes, a kernel and a Qt-based client can send
211 really starting two processes, a kernel and a Qt-based client can send
212 commands to and receive results from that kernel. If there is already a kernel
212 commands to and receive results from that kernel. If there is already a kernel
213 running that you want to connect to, you can pass the ``--existing`` flag
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 which will be something like ``--existing kernel-19732.json`` but with
217 which will be something like ``--existing kernel-19732.json`` but with
218 different numbers which correspond to the Process ID of the kernel.
218 different numbers which correspond to the Process ID of the kernel.
219
219
220 You can read more about using `ipython qtconsole
220 You can read more about using `jupyter qtconsole
221 <http://jupyter.org/qtconsole/>`_, and
221 <http://jupyter.org/qtconsole/>`_, and
222 `ipython notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`_. There
222 `ipython notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`_. There
223 is also a :ref:`message spec <messaging>` which documents the protocol for
223 is also a :ref:`message spec <messaging>` which documents the protocol for
@@ -232,6 +232,11 b' and clients.'
232 Interactive parallel computing
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 Increasingly, parallel computer hardware, such as multicore CPUs, clusters and
240 Increasingly, parallel computer hardware, such as multicore CPUs, clusters and
236 supercomputers, is becoming ubiquitous. Over the last several years, we have
241 supercomputers, is becoming ubiquitous. Over the last several years, we have
237 developed an architecture within IPython that allows such hardware to be used
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 .. toctree::
20 .. toctree::
21 :maxdepth: 1
21 :maxdepth: 1
22
22
23 version5
24 development
23 development
24 version5
25 version4
25 version4
26 github-stats-4
26 github-stats-4
27 version3
27 version3
1 NO CONTENT: file was removed
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
NO CONTENT: file was removed
General Comments 0
You need to be logged in to leave comments. Login now