##// END OF EJS Templates
Documentation overhaul....
Matthias Bussonnier -
Show More
@@ -1,269 +1,273 b''
1 1 # -*- coding: utf-8 -*-
2 2 #
3 3 # IPython documentation build configuration file.
4 4
5 5 # NOTE: This file has been edited manually from the auto-generated one from
6 6 # sphinx. Do NOT delete and re-generate. If any changes from sphinx are
7 7 # needed, generate a scratch one and merge by hand any new fields needed.
8 8
9 9 #
10 10 # This file is execfile()d with the current directory set to its containing dir.
11 11 #
12 12 # The contents of this file are pickled, so don't put values in the namespace
13 13 # that aren't pickleable (module imports are okay, they're removed automatically).
14 14 #
15 15 # All configuration values have a default value; values that are commented out
16 16 # serve to show the default value.
17 17
18 18 import sys, os
19 19
20 20 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
21 21
22 22 if ON_RTD:
23 23 # Mock the presence of matplotlib, which we don't have on RTD
24 24 # see
25 25 # http://read-the-docs.readthedocs.io/en/latest/faq.html
26 26 tags.add('rtd')
27 27
28 28 # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
29 29 for name in ('config', 'api', 'magics'):
30 30 fname = 'autogen_{}.py'.format(name)
31 31 fpath = os.path.abspath(os.path.join('..', fname))
32 32 with open(fpath) as f:
33 33 exec(compile(f.read(), fname, 'exec'), {
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
40 44 # absolute, like shown here.
41 45 sys.path.insert(0, os.path.abspath('../sphinxext'))
42 46
43 47 # We load the ipython release info into a dict by explicit execution
44 48 iprelease = {}
45 49 exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease)
46 50
47 51 # General configuration
48 52 # ---------------------
49 53
50 54 # Add any Sphinx extension module names here, as strings. They can be extensions
51 55 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
52 56 extensions = [
53 57 'matplotlib.sphinxext.mathmpl',
54 58 'matplotlib.sphinxext.only_directives',
55 59 'matplotlib.sphinxext.plot_directive',
56 60 'sphinx.ext.autodoc',
57 61 'sphinx.ext.autosummary',
58 62 'sphinx.ext.doctest',
59 63 'sphinx.ext.inheritance_diagram',
60 64 'sphinx.ext.intersphinx',
61 65 'IPython.sphinxext.ipython_console_highlighting',
62 66 'IPython.sphinxext.ipython_directive',
63 67 'sphinx.ext.napoleon', # to preprocess docstrings
64 68 'github', # for easy GitHub links
65 69 'magics',
66 70 ]
67 71
68 72 if ON_RTD:
69 73 # Remove extensions not currently supported on RTD
70 74 extensions.remove('matplotlib.sphinxext.only_directives')
71 75 extensions.remove('matplotlib.sphinxext.mathmpl')
72 76 extensions.remove('matplotlib.sphinxext.plot_directive')
73 77 extensions.remove('IPython.sphinxext.ipython_directive')
74 78 extensions.remove('IPython.sphinxext.ipython_console_highlighting')
75 79
76 80 # Add any paths that contain templates here, relative to this directory.
77 81 templates_path = ['_templates']
78 82
79 83 # The suffix of source filenames.
80 84 source_suffix = '.rst'
81 85
82 86 if iprelease['_version_extra'] == 'dev':
83 87 rst_prolog = """
84 88 .. note::
85 89
86 90 This documentation is for a development version of IPython. There may be
87 91 significant differences from the latest stable release.
88 92
89 93 """
90 94
91 95 # The master toctree document.
92 96 master_doc = 'index'
93 97
94 98 # General substitutions.
95 99 project = 'IPython'
96 100 copyright = 'The IPython Development Team'
97 101
98 102 # ghissue config
99 103 github_project_url = "https://github.com/ipython/ipython"
100 104
101 105 # numpydoc config
102 106 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
103 107 numpydoc_class_members_toctree = False
104 108
105 109 # The default replacements for |version| and |release|, also used in various
106 110 # other places throughout the built documents.
107 111 #
108 112 # The full version, including alpha/beta/rc tags.
109 113 release = "%s" % iprelease['version']
110 114 # Just the X.Y.Z part, no '-dev'
111 115 version = iprelease['version'].split('-', 1)[0]
112 116
113 117
114 118 # There are two options for replacing |today|: either, you set today to some
115 119 # non-false value, then it is used:
116 120 #today = ''
117 121 # Else, today_fmt is used as the format for a strftime call.
118 122 today_fmt = '%B %d, %Y'
119 123
120 124 # List of documents that shouldn't be included in the build.
121 125 #unused_docs = []
122 126
123 127 # Exclude these glob-style patterns when looking for source files. They are
124 128 # relative to the source/ directory.
125 129 exclude_patterns = ['whatsnew/pr']
126 130
127 131
128 132 # If true, '()' will be appended to :func: etc. cross-reference text.
129 133 #add_function_parentheses = True
130 134
131 135 # If true, the current module name will be prepended to all description
132 136 # unit titles (such as .. function::).
133 137 #add_module_names = True
134 138
135 139 # If true, sectionauthor and moduleauthor directives will be shown in the
136 140 # output. They are ignored by default.
137 141 #show_authors = False
138 142
139 143 # The name of the Pygments (syntax highlighting) style to use.
140 144 pygments_style = 'sphinx'
141 145
142 146 # Set the default role so we can use `foo` instead of ``foo``
143 147 default_role = 'literal'
144 148
145 149 # Options for HTML output
146 150 # -----------------------
147 151
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
155 159 # "<project> v<release> documentation".
156 160 #html_title = None
157 161
158 162 # The name of an image file (within the static path) to place at the top of
159 163 # the sidebar.
160 164 #html_logo = None
161 165
162 166 # Add any paths that contain custom static files (such as style sheets) here,
163 167 # relative to this directory. They are copied after the builtin static files,
164 168 # so a file named "default.css" will overwrite the builtin "default.css".
165 169 html_static_path = ['_static']
166 170
167 171 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
168 172 # using the given strftime format.
169 173 html_last_updated_fmt = '%b %d, %Y'
170 174
171 175 # If true, SmartyPants will be used to convert quotes and dashes to
172 176 # typographically correct entities.
173 177 #html_use_smartypants = True
174 178
175 179 # Custom sidebar templates, maps document names to template names.
176 180 #html_sidebars = {}
177 181
178 182 # Additional templates that should be rendered to pages, maps page names to
179 183 # template names.
180 184 html_additional_pages = {
181 185 'interactive/htmlnotebook': 'notebook_redirect.html',
182 186 'interactive/notebook': 'notebook_redirect.html',
183 187 'interactive/nbconvert': 'notebook_redirect.html',
184 188 'interactive/public_server': 'notebook_redirect.html',
185 189 }
186 190
187 191 # If false, no module index is generated.
188 192 #html_use_modindex = True
189 193
190 194 # If true, the reST sources are included in the HTML build as _sources/<name>.
191 195 #html_copy_source = True
192 196
193 197 # If true, an OpenSearch description file will be output, and all pages will
194 198 # contain a <link> tag referring to it. The value of this option must be the
195 199 # base URL from which the finished HTML is served.
196 200 #html_use_opensearch = ''
197 201
198 202 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
199 203 #html_file_suffix = ''
200 204
201 205 # Output file base name for HTML help builder.
202 206 htmlhelp_basename = 'ipythondoc'
203 207
204 208 intersphinx_mapping = {'python': ('http://docs.python.org/3/', None),
205 209 'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None),
206 210 'traitlets': ('http://traitlets.readthedocs.io/en/latest/', None),
207 211 'jupyterclient': ('http://jupyter-client.readthedocs.io/en/latest/', None),
208 212 'ipyparallel': ('http://ipyparallel.readthedocs.io/en/latest/', None),
209 213 'jupyter': ('http://jupyter.readthedocs.io/en/latest/', None),
210 214 }
211 215
212 216 # Options for LaTeX output
213 217 # ------------------------
214 218
215 219 # The paper size ('letter' or 'a4').
216 220 latex_paper_size = 'letter'
217 221
218 222 # The font size ('10pt', '11pt' or '12pt').
219 223 latex_font_size = '11pt'
220 224
221 225 # Grouping the document tree into LaTeX files. List of tuples
222 226 # (source start file, target name, title, author, document class [howto/manual]).
223 227
224 228 latex_documents = [
225 229 ('index', 'ipython.tex', 'IPython Documentation',
226 230 u"""The IPython Development Team""", 'manual', True),
227 231 ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
228 232 'Using IPython on Windows HPC Server 2008',
229 233 u"Brian E. Granger", 'manual', True)
230 234 ]
231 235
232 236 # The name of an image file (relative to this directory) to place at the top of
233 237 # the title page.
234 238 #latex_logo = None
235 239
236 240 # For "manual" documents, if this is true, then toplevel headings are parts,
237 241 # not chapters.
238 242 #latex_use_parts = False
239 243
240 244 # Additional stuff for the LaTeX preamble.
241 245 #latex_preamble = ''
242 246
243 247 # Documents to append as an appendix to all manuals.
244 248 #latex_appendices = []
245 249
246 250 # If false, no module index is generated.
247 251 latex_use_modindex = True
248 252
249 253
250 254 # Options for texinfo output
251 255 # --------------------------
252 256
253 257 texinfo_documents = [
254 258 (master_doc, 'ipython', 'IPython Documentation',
255 259 'The IPython Development Team',
256 260 'IPython',
257 261 'IPython Documentation',
258 262 'Programming',
259 263 1),
260 264 ]
261 265
262 266 modindex_common_prefix = ['IPython.']
263 267
264 268
265 269 # Cleanup
266 270 # -------
267 271 # delete release info to avoid pickling errors from sphinx
268 272
269 273 del iprelease
@@ -1,189 +1,193 b''
1 1 .. _release_process:
2 2
3 3 =======================
4 4 IPython release process
5 5 =======================
6 6
7 7 This document contains the process that is used to create an IPython release.
8 8
9 9 Conveniently, the `release` script in the `tools` directory of the `IPython`
10 10 repository automates most of the release process. This document serves as a
11 11 handy reminder and checklist for the release manager.
12 12
13 13 1. Set Environment variables
14 14 ----------------------------
15 15
16 16 Set environment variables to document previous release tag, current
17 17 release milestone, current release version, and git tag::
18 18
19 19 PREV_RELEASE=4.0.0
20 20 MILESTONE=4.1
21 21 VERSION=4.1.0
22 22 BRANCH=master
23 23
24 24 These variables may be used later to copy/paste as answers to the script
25 25 questions instead of typing the appropriate command when the time comes. These
26 26 variables are not used by the scripts directly; therefore, there is no need to
27 27 `export` the variables.
28 28
29 29 2. Create GitHub stats and finish release note
30 30 ----------------------------------------------
31 31
32 32 .. note::
33 33
34 34 Before generating the GitHub stats, verify that all closed issues and
35 35 pull requests have `appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
36 36 `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
37 37 should return no results before creating the GitHub stats.
38 38
39 39 If a major release:
40 40
41 41 - merge any pull request notes into what's new::
42 42
43 43 python tools/update_whatsnew.py
44 44
45 45 - update `docs/source/whatsnew/development.rst`, to ensure it covers
46 46 the major release features
47 47 - move the contents of `development.rst` to `versionX.rst` where `X` is
48 48 the numerical release version
49 49 - generate summary of GitHub contributions, which can be done with::
50 50
51 51 python tools/github_stats.py --milestone $MILESTONE > stats.rst
52 52
53 53 which may need some manual cleanup of `stats.rst`. Add the cleaned
54 54 `stats.rst` results to `docs/source/whatsnew/github-stats-X.rst` where
55 55 `X` is the numerical release version. If creating a major release, make
56 56 a new `github-stats-X.rst` file; if creating a minor release, the
57 57 content from `stats.rst` may simply be added to the top of an existing
58 58 `github-stats-X.rst` file.
59 59
60 60 To find duplicates and update `.mailmap`, use::
61 61
62 62 git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
63 63
64 64 3. Make sure the repository is clean
65 65 ------------------------------------
66 66
67 67 of any file that could be problematic.
68 68 Remove all non-tracked files with:
69 69
70 70 .. code::
71 71
72 72 git clean -xfdi
73 73
74 74 This will ask for confirmation before removing all untracked files. Make
75 75 sure the ``dist/`` folder is clean to avoid any stale builds from
76 76 previous build attempts.
77 77
78 78
79 79 4. Update the release version number
80 80 ------------------------------------
81 81
82 82 Edit `IPython/core/release.py` to have the current version.
83 83
84 84 in particular, update version number and ``_version_extra`` content in
85 85 ``IPython/core/release.py``.
86 86
87 87 Make sure the version number matches pep440, in particular, `rc` and `beta` are
88 88 not separated by `.` or the `sdist` and `bdist` will appear as different
89 89 releases. For example, a valid version number for a release candidate (rc)
90 90 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
97 100 Running `tools/build_release` does all the file checking and building that
98 101 the real release script will do. This makes test installations, checks that
99 102 the build procedure runs OK, and tests other steps in the release process.
100 103
101 104 The `build_release` script will in particular verify that the version number
102 105 match PEP 440, in order to avoid surprise at the time of build upload.
103 106
104 107 We encourage creating a test build of the docs as well.
105 108
106 109 6. Create and push the new tag
107 110 ------------------------------
108 111
109 112 Commit the changes to release.py::
110 113
111 114 git commit -am "release $VERSION"
112 115 git push origin $BRANCH
113 116
114 117 Create and push the tag::
115 118
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 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 125 git commit -am "back to development"
122 126 git push origin $BRANCH
123 127
124 128 7. Get a fresh clone
125 129 --------------------
126 130
127 131 Get a fresh clone of the tag for building the release::
128 132
129 133 cd /tmp
130 134 git clone --depth 1 https://github.com/ipython/ipython.git -b "$VERSION"
131 135
132 136 8. Run the release script
133 137 -------------------------
134 138
135 139 Run the `release` script, this step requires having a current wheel, Python >=3.4 and Python 2.7.::
136 140
137 141 cd tools && ./release
138 142
139 143 This makes the tarballs, zipfiles, and wheels, and put them under the `dist/`
140 144 folder. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading
141 145 them to PyPI.
142 146
143 147 Use the following to actually upload the result of the build:
144 148
145 149 ./release upload
146 150
147 151 It should posts them to ``archive.ipython.org`` and registers the release
148 152 with PyPI if you have the various authorisations.
149 153
150 154 You might need to use `twine <https://github.com/pypa/twine>`_ (`twine upload
151 155 dist/*`) manually to actually upload on PyPI. Unlike setuptools, twine is able
152 156 to upload packages over SSL.
153 157
154 158
155 159 9. Draft a short release announcement
156 160 -------------------------------------
157 161
158 162 The announcement should include:
159 163
160 164 - release highlights
161 165 - a link to the html version of the *What's new* section of the documentation
162 166 - a link to upgrade or installation tips (if necessary)
163 167
164 168 Post the announcement to the mailing list and or blog, and link from Twitter.
165 169
166 170 10. Update milestones on GitHub
167 171 -------------------------------
168 172
169 173 These steps will bring milestones up to date:
170 174
171 175 - close the just released milestone
172 176 - open a new milestone for the next release (x, y+1), if the milestone doesn't
173 177 exist already
174 178
175 179 11. Update the IPython website
176 180 ------------------------------
177 181
178 182 The IPython website should document the new release:
179 183
180 184 - add release announcement (news, announcements)
181 185 - update current version and download links
182 186 - update links on the documentation page (especially if a major release)
183 187
184 188 12. Celebrate!
185 189 --------------
186 190
187 191 Celebrate the release and please thank the contributors for their work. Great
188 192 job!
189 193
@@ -1,41 +1,110 b''
1 .. _introduction:
2
1 3 =====================
2 4 IPython Documentation
3 5 =====================
4 6
5 7 .. htmlonly::
6 8
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
21 90 interactive/index
22 91 config/index
23 92 development/index
24 93 coredev/index
25 94 api/index
26 95 about/index
27 96
28 97 .. seealso::
29 98
30 99 `Jupyter documentation <http://jupyter.readthedocs.io/en/latest/>`__
31 100 The Notebook code and many other pieces formerly in IPython are now parts
32 101 of Project Jupyter.
33 102 `ipyparallel documentation <http://ipyparallel.readthedocs.io/en/latest/>`__
34 103 Formerly ``IPython.parallel``.
35 104
36 105
37 106 .. htmlonly::
38 107 * :ref:`genindex`
39 108 * :ref:`modindex`
40 109 * :ref:`search`
41 110
@@ -1,12 +1,60 b''
1 1 .. _install_index:
2 2
3 3 ============
4 4 Installation
5 5 ============
6 6
7 7 .. toctree::
8 :maxdepth: 2
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,180 +1,131 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 Quickstart
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,
35 29 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 can be installed via :command:`pip`.
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://pypi.python.org/pypi/pip>`__.
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
46 40 `Python's documentation <http://docs.python.org>`_.
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
68 61 $ pip install ipython
69 62
70 63 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
78 71 <https://pypi.python.org/pypi/ipython>`__. Then do the following:
79 72
80 73 .. code-block:: bash
81 74
82 75 $ tar -xzf ipython.tar.gz
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
95 98 need to have Git installed on your system. Then do:
96 99
97 100 .. code-block:: bash
98 101
99 102 $ git clone https://github.com/ipython/ipython.git
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. If
104 you have :mod:`pip`, you can replace the last step by:
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 places.
114 the appropriate location.
112 115
113 116 Then, if you want to update your IPython at any time, do:
114 117
115 118 .. code-block:: bash
116 119
117 120 $ git pull
118 121
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, so a
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,291 +1,296 b''
1 1 .. _overview:
2 2
3 ============
4 Introduction
5 ============
6
3 ========
7 4 Overview
8 5 ========
9 6
10 7 One of Python's most useful features is its interactive interpreter.
11 8 It allows for very fast testing of ideas without the overhead of
12 9 creating test files as is typical in most programming languages.
13 10 However, the interpreter supplied with the standard Python distribution
14 11 is somewhat limited for extended interactive use.
15 12
16 13 The goal of IPython is to create a comprehensive environment for
17 14 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
28 28 Enhanced interactive Python shell
29 29 =================================
30 30
31 31 IPython's interactive shell (:command:`ipython`), has the following goals,
32 32 amongst others:
33 33
34 34 1. Provide an interactive shell superior to Python's default. IPython
35 35 has many features for tab-completion, object introspection, system shell
36 36 access, command history retrieval across sessions, and its own special
37 37 command system for adding functionality when working interactively. It
38 38 tries to be a very efficient environment both for Python code development
39 39 and for exploration of problems using Python objects (in situations like
40 40 data analysis).
41 41
42 42 2. Serve as an embeddable, ready to use interpreter for your own
43 43 programs. An interactive IPython shell can be started with a single call
44 44 from inside another program, providing access to the current namespace.
45 45 This can be very useful both for debugging purposes and for situations
46 46 where a blend of batch-processing and interactive exploration are needed.
47 47
48 48 3. Offer a flexible framework which can be used as the base
49 49 environment for working with other systems, with Python as the underlying
50 50 bridge language. Specifically scientific environments like Mathematica,
51 51 IDL and Matlab inspired its design, but similar ideas can be
52 52 useful in many fields.
53 53
54 54 4. Allow interactive testing of threaded graphical toolkits. IPython
55 55 has support for interactive, non-blocking control of GTK, Qt, WX, GLUT, and
56 56 OS X applications via special threading flags. The normal Python
57 57 shell can only do this for Tkinter applications.
58 58
59 59 Main features of the interactive shell
60 60 --------------------------------------
61 61
62 62 * Dynamic object introspection. One can access docstrings, function
63 63 definition prototypes, source code, source files and other details
64 64 of any object accessible to the interpreter with a single
65 65 keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
66 66
67 67 * Searching through modules and namespaces with :samp:`*` wildcards, both
68 68 when using the :samp:`?` system and via the :samp:`%psearch` command.
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 readline library, and
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
77 76 * Numbered input/output prompts with command history (persistent
78 77 across sessions and tied to each profile), full searching in this
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
86 85 * Alias facility for defining your own system aliases.
87 86
88 87 * Complete system shell access. Lines starting with :samp:`!` are passed
89 88 directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd`
90 89 captures shell output into python variables for further use.
91 90
92 91 * The ability to expand python variables when calling the system shell. In a
93 92 shell command, any python variable prefixed with :samp:`$` is expanded. A
94 93 double :samp:`$$` allows passing a literal :samp:`$` to the shell (for access
95 94 to shell and environment variables like :envvar:`PATH`).
96 95
97 96 * Filesystem navigation, via a magic :samp:`%cd` command, along with a
98 97 persistent bookmark system (using :samp:`%bookmark`) for fast access to
99 98 frequently visited directories.
100 99
101 100 * A lightweight persistence framework via the :samp:`%store` command, which
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 (optional) of code as you type (through the
106 readline library).
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
110 109 stored persistently via :samp:`%store` and edited via :samp:`%edit`.
111 110
112 111 * Session logging (you can then later use these logs as code in your
113 112 programs). Logs can optionally timestamp all input, and also store
114 113 session output (marked as comments, so the log remains valid
115 114 Python source code).
116 115
117 116 * Session restoring: logs can be replayed to restore a previous
118 117 session to the state where you left it.
119 118
120 119 * Verbose and colored exception traceback printouts. Easier to parse
121 120 visually, and in verbose mode they produce a lot of useful
122 121 debugging information (basically a terminal version of the cgitb
123 122 module).
124 123
125 124 * Auto-parentheses via the :samp:`%autocall` command: callable objects can be
126 125 executed without parentheses: :samp:`sin 3` is automatically converted to
127 126 :samp:`sin(3)`
128 127
129 128 * Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
130 129 auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
131 130 automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
132 131 becomes :samp:`my_function("a b")`.
133 132
134 133 * Extensible input syntax. You can define filters that pre-process
135 134 user input to simplify input in special situations. This allows
136 135 for example pasting multi-line code fragments which start with
137 136 :samp:`>>>` or :samp:`...` such as those from other python sessions or the
138 137 standard Python documentation.
139 138
140 139 * Flexible :ref:`configuration system <config_overview>`. It uses a
141 140 configuration file which allows permanent setting of all command-line
142 141 options, module loading, code and file execution. The system allows
143 142 recursive file inclusion, so you can have a base file with defaults and
144 143 layers which load other customizations for particular projects.
145 144
146 145 * Embeddable. You can call IPython as a python shell inside your own
147 146 python programs. This can be used both for debugging code or for
148 147 providing interactive abilities to your programs with knowledge
149 148 about the local namespaces (very useful in debugging and data
150 149 analysis situations).
151 150
152 151 * Easy debugger access. You can set IPython to call up an enhanced version of
153 152 the Python debugger (pdb) every time there is an uncaught exception. This
154 153 drops you inside the code which triggered the exception with all the data
155 154 live and it is possible to navigate the stack to rapidly isolate the source
156 155 of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run
157 156 any script under pdb's control, automatically setting initial breakpoints for
158 157 you. This version of pdb has IPython-specific improvements, including
159 158 tab-completion and traceback coloring support. For even easier debugger
160 159 access, try :samp:`%debug` after seeing an exception.
161 160
162 161 * Profiler support. You can run single statements (similar to
163 162 :samp:`profile.run()`) or complete programs under the profiler's control.
164 163 While this is possible with standard cProfile or profile modules,
165 164 IPython wraps this functionality with magic commands (see :samp:`%prun`
166 165 and :samp:`%run -p`) convenient for rapid interactive work.
167 166
168 167 * Simple timing information. You can use the :samp:`%timeit` command to get
169 168 the execution time of a Python statement or expression. This machinery is
170 169 intelligent enough to do more repetitions for commands that finish very
171 170 quickly in order to get a better estimate of their running time.
172 171
173 172 .. sourcecode:: ipython
174 173
175 174 In [1]: %timeit 1+1
176 175 10000000 loops, best of 3: 25.5 ns per loop
177 176
178 177 In [2]: %timeit [math.sin(x) for x in range(5000)]
179 178 1000 loops, best of 3: 719 µs per loop
180 179
181 180 ..
182 181
183 182 To get the timing information for more than one expression, use the
184 183 :samp:`%%timeit` cell magic command.
185 184
186 185
187 186 * Doctest support. The special :samp:`%doctest_mode` command toggles a mode
188 187 to use doctest-compatible prompts, so you can use IPython sessions as
189 188 doctest code. By default, IPython also allows you to paste existing
190 189 doctests, and strips out the leading :samp:`>>>` and :samp:`...` prompts in
191 190 them.
192 191
193 192 .. _ipythonzmq:
194 193
195 194 Decoupled two-process model
196 195 ==============================
197 196
198 197 IPython has abstracted and extended the notion of a traditional
199 198 *Read-Evaluate-Print Loop* (REPL) environment by decoupling the *evaluation*
200 199 into its own process. We call this process a **kernel**: it receives execution
201 200 instructions from clients and communicates the results back to them.
202 201
203 202 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. This includes ``ipython
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 ``ipython qtconsole``, you're
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
214 214 which will skip initiating a new kernel and connect to the most recent kernel,
215 215 instead. To connect to a specific kernel once you have several kernels
216 216 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 `ipython qtconsole
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
224 224 communication between kernels
225 225 and clients.
226 226
227 227 .. seealso::
228 228
229 229 `Frontend/Kernel Model`_ example notebook
230 230
231 231
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
238 243 quickly and easily from Python. Moreover, this architecture is designed to
239 244 support interactive and collaborative parallel computing.
240 245
241 246 The main features of this system are:
242 247
243 248 * Quickly parallelize Python code from an interactive Python/IPython session.
244 249
245 250 * A flexible and dynamic process model that be deployed on anything from
246 251 multicore workstations to supercomputers.
247 252
248 253 * An architecture that supports many different styles of parallelism, from
249 254 message passing to task farming. And all of these styles can be handled
250 255 interactively.
251 256
252 257 * Both blocking and fully asynchronous interfaces.
253 258
254 259 * High level APIs that enable many things to be parallelized in a few lines
255 260 of code.
256 261
257 262 * Write parallel code that will run unchanged on everything from multicore
258 263 workstations to supercomputers.
259 264
260 265 * Full integration with Message Passing libraries (MPI).
261 266
262 267 * Capabilities based security model with full encryption of network connections.
263 268
264 269 * Share live parallel jobs with other users securely. We call this
265 270 collaborative parallel computing.
266 271
267 272 * Dynamically load balanced task farming system.
268 273
269 274 * Robust error handling. Python exceptions raised in parallel execution are
270 275 gathered and presented to the top-level code.
271 276
272 277 For more information, see our :ref:`overview <parallel_index>` of using IPython
273 278 for parallel computing.
274 279
275 280 Portability and Python requirements
276 281 -----------------------------------
277 282
278 283 As of the 2.0 release, IPython works with Python 2.7 and 3.3 or above.
279 284 Version 1.0 additionally worked with Python 2.6 and 3.2.
280 285 Version 0.12 was the first version to fully support Python 3.
281 286
282 287 IPython is known to work on the following operating systems:
283 288
284 289 * Linux
285 290 * Most other Unix-like OSs (AIX, Solaris, BSD, etc.)
286 291 * Mac OS X
287 292 * Windows (CygWin, XP, Vista, etc.)
288 293
289 294 See :ref:`here <install_index>` for instructions on how to install IPython.
290 295
291 296 .. include:: links.txt
@@ -1,44 +1,44 b''
1 1 .. Developers should add in this file, during each release cycle, information
2 2 .. about important changes they've made, in a summary format that's meant for
3 3 .. end users. For each release we normally have three sections: features, bug
4 4 .. fixes and api breakage.
5 5 .. Please remember to credit the authors of the contributions by name,
6 6 .. especially when they are new users or developers who do not regularly
7 7 .. participate in IPython's development.
8 8
9 9 .. _whatsnew_index:
10 10
11 11 =====================
12 12 What's new in IPython
13 13 =====================
14 14
15 15 This section documents the changes that have been made in various versions of
16 16 IPython. Users should consult these pages to learn about new features, bug
17 17 fixes and backwards incompatibilities. Developers should summarize the
18 18 development work they do here in a user friendly format.
19 19
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
28 28 github-stats-3
29 29 version3_widget_migration
30 30 version2.0
31 31 github-stats-2.0
32 32 version1.0
33 33 github-stats-1.0
34 34 version0.13
35 35 github-stats-0.13
36 36 version0.12
37 37 github-stats-0.12
38 38 version0.11
39 39 github-stats-0.11
40 40 version0.10
41 41 version0.9
42 42 version0.8
43 43
44 44
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