Show More
@@ -1,282 +1,284 b'' | |||||
1 | # -*- coding: utf-8 -*- |
|
1 | # -*- coding: utf-8 -*- | |
2 | # |
|
2 | # | |
3 | # IPython documentation build configuration file. |
|
3 | # IPython documentation build configuration file. | |
4 |
|
4 | |||
5 | # NOTE: This file has been edited manually from the auto-generated one from |
|
5 | # NOTE: This file has been edited manually from the auto-generated one from | |
6 | # sphinx. Do NOT delete and re-generate. If any changes from sphinx are |
|
6 | # sphinx. Do NOT delete and re-generate. If any changes from sphinx are | |
7 | # needed, generate a scratch one and merge by hand any new fields needed. |
|
7 | # needed, generate a scratch one and merge by hand any new fields needed. | |
8 |
|
8 | |||
9 | # |
|
9 | # | |
10 | # This file is execfile()d with the current directory set to its containing dir. |
|
10 | # This file is execfile()d with the current directory set to its containing dir. | |
11 | # |
|
11 | # | |
12 | # The contents of this file are pickled, so don't put values in the namespace |
|
12 | # The contents of this file are pickled, so don't put values in the namespace | |
13 | # that aren't pickleable (module imports are okay, they're removed automatically). |
|
13 | # that aren't pickleable (module imports are okay, they're removed automatically). | |
14 | # |
|
14 | # | |
15 | # All configuration values have a default value; values that are commented out |
|
15 | # All configuration values have a default value; values that are commented out | |
16 | # serve to show the default value. |
|
16 | # serve to show the default value. | |
17 |
|
17 | |||
18 | import sys, os |
|
18 | import sys, os | |
19 |
|
19 | |||
20 | ON_RTD = os.environ.get('READTHEDOCS', None) == 'True' |
|
20 | ON_RTD = os.environ.get('READTHEDOCS', None) == 'True' | |
21 |
|
21 | |||
22 | if ON_RTD: |
|
22 | if ON_RTD: | |
23 | # Mock the presence of matplotlib, which we don't have on RTD |
|
23 | # Mock the presence of matplotlib, which we don't have on RTD | |
24 | # see |
|
24 | # see | |
25 | # http://read-the-docs.readthedocs.io/en/latest/faq.html |
|
25 | # http://read-the-docs.readthedocs.io/en/latest/faq.html | |
26 | tags.add('rtd') |
|
26 | tags.add('rtd') | |
27 |
|
27 | |||
28 | # RTD doesn't use the Makefile, so re-run autogen_{things}.py here. |
|
28 | # RTD doesn't use the Makefile, so re-run autogen_{things}.py here. | |
29 | for name in ('config', 'api', 'magics'): |
|
29 | for name in ('config', 'api', 'magics'): | |
30 | fname = 'autogen_{}.py'.format(name) |
|
30 | fname = 'autogen_{}.py'.format(name) | |
31 | fpath = os.path.abspath(os.path.join('..', fname)) |
|
31 | fpath = os.path.abspath(os.path.join('..', fname)) | |
32 | with open(fpath) as f: |
|
32 | with open(fpath) as f: | |
33 | exec(compile(f.read(), fname, 'exec'), { |
|
33 | exec(compile(f.read(), fname, 'exec'), { | |
34 | '__file__': fpath, |
|
34 | '__file__': fpath, | |
35 | '__name__': '__main__', |
|
35 | '__name__': '__main__', | |
36 | }) |
|
36 | }) | |
37 | else: |
|
37 | else: | |
38 | import sphinx_rtd_theme |
|
38 | import sphinx_rtd_theme | |
39 | html_theme = "sphinx_rtd_theme" |
|
39 | html_theme = "sphinx_rtd_theme" | |
40 | html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] |
|
40 | html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] | |
41 |
|
41 | |||
42 | # 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 | |
43 | # 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 | |
44 | # absolute, like shown here. |
|
44 | # absolute, like shown here. | |
45 | sys.path.insert(0, os.path.abspath('../sphinxext')) |
|
45 | sys.path.insert(0, os.path.abspath('../sphinxext')) | |
46 |
|
46 | |||
47 | # We load the ipython release info into a dict by explicit execution |
|
47 | # We load the ipython release info into a dict by explicit execution | |
48 | iprelease = {} |
|
48 | iprelease = {} | |
49 | exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease) |
|
49 | exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease) | |
50 |
|
50 | |||
51 | # General configuration |
|
51 | # General configuration | |
52 | # --------------------- |
|
52 | # --------------------- | |
53 |
|
53 | |||
54 | # Add any Sphinx extension module names here, as strings. They can be extensions |
|
54 | # Add any Sphinx extension module names here, as strings. They can be extensions | |
55 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
|
55 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. | |
56 | extensions = [ |
|
56 | extensions = [ | |
57 | 'matplotlib.sphinxext.mathmpl', |
|
57 | 'matplotlib.sphinxext.mathmpl', | |
58 | 'matplotlib.sphinxext.only_directives', |
|
58 | 'matplotlib.sphinxext.only_directives', | |
59 | 'matplotlib.sphinxext.plot_directive', |
|
59 | 'matplotlib.sphinxext.plot_directive', | |
60 | 'sphinx.ext.autodoc', |
|
60 | 'sphinx.ext.autodoc', | |
61 | 'sphinx.ext.autosummary', |
|
61 | 'sphinx.ext.autosummary', | |
62 | 'sphinx.ext.doctest', |
|
62 | 'sphinx.ext.doctest', | |
63 | 'sphinx.ext.inheritance_diagram', |
|
63 | 'sphinx.ext.inheritance_diagram', | |
64 | 'sphinx.ext.intersphinx', |
|
64 | 'sphinx.ext.intersphinx', | |
65 | 'IPython.sphinxext.ipython_console_highlighting', |
|
65 | 'IPython.sphinxext.ipython_console_highlighting', | |
66 | 'IPython.sphinxext.ipython_directive', |
|
66 | 'IPython.sphinxext.ipython_directive', | |
67 | 'sphinx.ext.napoleon', # to preprocess docstrings |
|
67 | 'sphinx.ext.napoleon', # to preprocess docstrings | |
68 | 'github', # for easy GitHub links |
|
68 | 'github', # for easy GitHub links | |
69 | 'magics', |
|
69 | 'magics', | |
70 | ] |
|
70 | ] | |
71 |
|
71 | |||
72 | if ON_RTD: |
|
72 | if ON_RTD: | |
73 | # Remove extensions not currently supported on RTD |
|
73 | # Remove extensions not currently supported on RTD | |
74 | extensions.remove('matplotlib.sphinxext.only_directives') |
|
74 | extensions.remove('matplotlib.sphinxext.only_directives') | |
75 | extensions.remove('matplotlib.sphinxext.mathmpl') |
|
75 | extensions.remove('matplotlib.sphinxext.mathmpl') | |
76 | extensions.remove('matplotlib.sphinxext.plot_directive') |
|
76 | extensions.remove('matplotlib.sphinxext.plot_directive') | |
77 | extensions.remove('IPython.sphinxext.ipython_directive') |
|
77 | extensions.remove('IPython.sphinxext.ipython_directive') | |
78 | extensions.remove('IPython.sphinxext.ipython_console_highlighting') |
|
78 | extensions.remove('IPython.sphinxext.ipython_console_highlighting') | |
79 |
|
79 | |||
80 | # Add any paths that contain templates here, relative to this directory. |
|
80 | # Add any paths that contain templates here, relative to this directory. | |
81 | templates_path = ['_templates'] |
|
81 | templates_path = ['_templates'] | |
82 |
|
82 | |||
83 | # The suffix of source filenames. |
|
83 | # The suffix of source filenames. | |
84 | source_suffix = '.rst' |
|
84 | source_suffix = '.rst' | |
85 |
|
85 | |||
86 | def is_stable(extra): |
|
86 | def is_stable(extra): | |
87 | for ext in {'dev', 'b', 'rc'}: |
|
87 | for ext in {'dev', 'b', 'rc'}: | |
88 | if ext in extra: |
|
88 | if ext in extra: | |
89 | return False |
|
89 | return False | |
90 | return True |
|
90 | return True | |
91 |
|
91 | |||
92 | if is_stable(iprelease['_version_extra']): |
|
92 | if is_stable(iprelease['_version_extra']): | |
93 | tags.add('ipystable') |
|
93 | tags.add('ipystable') | |
94 | else: |
|
94 | else: | |
95 | tags.add('ipydev') |
|
95 | tags.add('ipydev') | |
96 | rst_prolog = """ |
|
96 | rst_prolog = """ | |
97 | .. warning:: |
|
97 | .. warning:: | |
98 |
|
98 | |||
99 | This documentation is for a development version of IPython. There may be |
|
99 | This documentation is for a development version of IPython. There may be | |
100 | significant differences from the latest stable release. |
|
100 | significant differences from the latest stable release. | |
101 |
|
101 | |||
102 | """ |
|
102 | """ | |
103 |
|
103 | |||
104 | # The master toctree document. |
|
104 | # The master toctree document. | |
105 | master_doc = 'index' |
|
105 | master_doc = 'index' | |
106 |
|
106 | |||
107 | # General substitutions. |
|
107 | # General substitutions. | |
108 | project = 'IPython' |
|
108 | project = 'IPython' | |
109 | copyright = 'The IPython Development Team' |
|
109 | copyright = 'The IPython Development Team' | |
110 |
|
110 | |||
111 | # ghissue config |
|
111 | # ghissue config | |
112 | github_project_url = "https://github.com/ipython/ipython" |
|
112 | github_project_url = "https://github.com/ipython/ipython" | |
113 |
|
113 | |||
114 | # numpydoc config |
|
114 | # numpydoc config | |
115 | numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings |
|
115 | numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings | |
116 | numpydoc_class_members_toctree = False |
|
116 | numpydoc_class_members_toctree = False | |
117 |
|
117 | |||
118 | # The default replacements for |version| and |release|, also used in various |
|
118 | # The default replacements for |version| and |release|, also used in various | |
119 | # other places throughout the built documents. |
|
119 | # other places throughout the built documents. | |
120 | # |
|
120 | # | |
121 | # The full version, including alpha/beta/rc tags. |
|
121 | # The full version, including alpha/beta/rc tags. | |
122 | release = "%s" % iprelease['version'] |
|
122 | release = "%s" % iprelease['version'] | |
123 | # Just the X.Y.Z part, no '-dev' |
|
123 | # Just the X.Y.Z part, no '-dev' | |
124 | version = iprelease['version'].split('-', 1)[0] |
|
124 | version = iprelease['version'].split('-', 1)[0] | |
125 |
|
125 | |||
126 |
|
126 | |||
127 | # There are two options for replacing |today|: either, you set today to some |
|
127 | # There are two options for replacing |today|: either, you set today to some | |
128 | # non-false value, then it is used: |
|
128 | # non-false value, then it is used: | |
129 | #today = '' |
|
129 | #today = '' | |
130 | # Else, today_fmt is used as the format for a strftime call. |
|
130 | # Else, today_fmt is used as the format for a strftime call. | |
131 | today_fmt = '%B %d, %Y' |
|
131 | today_fmt = '%B %d, %Y' | |
132 |
|
132 | |||
133 | # List of documents that shouldn't be included in the build. |
|
133 | # List of documents that shouldn't be included in the build. | |
134 | #unused_docs = [] |
|
134 | #unused_docs = [] | |
135 |
|
135 | |||
136 | # Exclude these glob-style patterns when looking for source files. They are |
|
136 | # Exclude these glob-style patterns when looking for source files. They are | |
137 | # relative to the source/ directory. |
|
137 | # relative to the source/ directory. | |
138 | exclude_patterns = ['whatsnew/pr'] |
|
138 | exclude_patterns = ['whatsnew/pr'] | |
139 |
|
139 | |||
140 |
|
140 | |||
141 | # If true, '()' will be appended to :func: etc. cross-reference text. |
|
141 | # If true, '()' will be appended to :func: etc. cross-reference text. | |
142 | #add_function_parentheses = True |
|
142 | #add_function_parentheses = True | |
143 |
|
143 | |||
144 | # If true, the current module name will be prepended to all description |
|
144 | # If true, the current module name will be prepended to all description | |
145 | # unit titles (such as .. function::). |
|
145 | # unit titles (such as .. function::). | |
146 | #add_module_names = True |
|
146 | #add_module_names = True | |
147 |
|
147 | |||
148 | # If true, sectionauthor and moduleauthor directives will be shown in the |
|
148 | # If true, sectionauthor and moduleauthor directives will be shown in the | |
149 | # output. They are ignored by default. |
|
149 | # output. They are ignored by default. | |
150 | #show_authors = False |
|
150 | #show_authors = False | |
151 |
|
151 | |||
152 | # The name of the Pygments (syntax highlighting) style to use. |
|
152 | # The name of the Pygments (syntax highlighting) style to use. | |
153 | pygments_style = 'sphinx' |
|
153 | pygments_style = 'sphinx' | |
154 |
|
154 | |||
155 | # Set the default role so we can use `foo` instead of ``foo`` |
|
155 | # Set the default role so we can use `foo` instead of ``foo`` | |
156 | default_role = 'literal' |
|
156 | default_role = 'literal' | |
157 |
|
157 | |||
158 | # Options for HTML output |
|
158 | # Options for HTML output | |
159 | # ----------------------- |
|
159 | # ----------------------- | |
160 |
|
160 | |||
161 | # The style sheet to use for HTML and HTML Help pages. A file of that name |
|
161 | # The style sheet to use for HTML and HTML Help pages. A file of that name | |
162 | # must exist either in Sphinx' static/ path, or in one of the custom paths |
|
162 | # must exist either in Sphinx' static/ path, or in one of the custom paths | |
163 | # given in html_static_path. |
|
163 | # given in html_static_path. | |
164 | # html_style = 'default.css' |
|
164 | # html_style = 'default.css' | |
165 | # html_favicon = 'favicon.ico' |
|
165 | ||
166 |
|
166 | |||
167 | # The name for this set of Sphinx documents. If None, it defaults to |
|
167 | # The name for this set of Sphinx documents. If None, it defaults to | |
168 | # "<project> v<release> documentation". |
|
168 | # "<project> v<release> documentation". | |
169 | #html_title = None |
|
169 | #html_title = None | |
170 |
|
170 | |||
171 | # The name of an image file (within the static path) to place at the top of |
|
171 | # The name of an image file (within the static path) to place at the top of | |
172 | # the sidebar. |
|
172 | # the sidebar. | |
173 | #html_logo = None |
|
173 | #html_logo = None | |
174 |
|
174 | |||
175 | # Add any paths that contain custom static files (such as style sheets) here, |
|
175 | # Add any paths that contain custom static files (such as style sheets) here, | |
176 | # relative to this directory. They are copied after the builtin static files, |
|
176 | # relative to this directory. They are copied after the builtin static files, | |
177 | # so a file named "default.css" will overwrite the builtin "default.css". |
|
177 | # so a file named "default.css" will overwrite the builtin "default.css". | |
178 | html_static_path = ['_static'] |
|
178 | html_static_path = ['_static'] | |
|
179 | ||||
|
180 | # Favicon needs the directory name | |||
179 | html_favicon = '_static/favicon.ico' |
|
181 | html_favicon = '_static/favicon.ico' | |
180 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
|
182 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, | |
181 | # using the given strftime format. |
|
183 | # using the given strftime format. | |
182 | html_last_updated_fmt = '%b %d, %Y' |
|
184 | html_last_updated_fmt = '%b %d, %Y' | |
183 |
|
185 | |||
184 | # If true, SmartyPants will be used to convert quotes and dashes to |
|
186 | # If true, SmartyPants will be used to convert quotes and dashes to | |
185 | # typographically correct entities. |
|
187 | # typographically correct entities. | |
186 | #html_use_smartypants = True |
|
188 | #html_use_smartypants = True | |
187 |
|
189 | |||
188 | # Custom sidebar templates, maps document names to template names. |
|
190 | # Custom sidebar templates, maps document names to template names. | |
189 | #html_sidebars = {} |
|
191 | #html_sidebars = {} | |
190 |
|
192 | |||
191 | # Additional templates that should be rendered to pages, maps page names to |
|
193 | # Additional templates that should be rendered to pages, maps page names to | |
192 | # template names. |
|
194 | # template names. | |
193 | html_additional_pages = { |
|
195 | html_additional_pages = { | |
194 | 'interactive/htmlnotebook': 'notebook_redirect.html', |
|
196 | 'interactive/htmlnotebook': 'notebook_redirect.html', | |
195 | 'interactive/notebook': 'notebook_redirect.html', |
|
197 | 'interactive/notebook': 'notebook_redirect.html', | |
196 | 'interactive/nbconvert': 'notebook_redirect.html', |
|
198 | 'interactive/nbconvert': 'notebook_redirect.html', | |
197 | 'interactive/public_server': 'notebook_redirect.html', |
|
199 | 'interactive/public_server': 'notebook_redirect.html', | |
198 | } |
|
200 | } | |
199 |
|
201 | |||
200 | # If false, no module index is generated. |
|
202 | # If false, no module index is generated. | |
201 | #html_use_modindex = True |
|
203 | #html_use_modindex = True | |
202 |
|
204 | |||
203 | # If true, the reST sources are included in the HTML build as _sources/<name>. |
|
205 | # If true, the reST sources are included in the HTML build as _sources/<name>. | |
204 | #html_copy_source = True |
|
206 | #html_copy_source = True | |
205 |
|
207 | |||
206 | # If true, an OpenSearch description file will be output, and all pages will |
|
208 | # If true, an OpenSearch description file will be output, and all pages will | |
207 | # contain a <link> tag referring to it. The value of this option must be the |
|
209 | # contain a <link> tag referring to it. The value of this option must be the | |
208 | # base URL from which the finished HTML is served. |
|
210 | # base URL from which the finished HTML is served. | |
209 | #html_use_opensearch = '' |
|
211 | #html_use_opensearch = '' | |
210 |
|
212 | |||
211 | # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). |
|
213 | # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). | |
212 | #html_file_suffix = '' |
|
214 | #html_file_suffix = '' | |
213 |
|
215 | |||
214 | # Output file base name for HTML help builder. |
|
216 | # Output file base name for HTML help builder. | |
215 | htmlhelp_basename = 'ipythondoc' |
|
217 | htmlhelp_basename = 'ipythondoc' | |
216 |
|
218 | |||
217 | intersphinx_mapping = {'python': ('http://docs.python.org/3/', None), |
|
219 | intersphinx_mapping = {'python': ('http://docs.python.org/3/', None), | |
218 | 'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None), |
|
220 | 'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None), | |
219 | 'traitlets': ('http://traitlets.readthedocs.io/en/latest/', None), |
|
221 | 'traitlets': ('http://traitlets.readthedocs.io/en/latest/', None), | |
220 | 'jupyterclient': ('http://jupyter-client.readthedocs.io/en/latest/', None), |
|
222 | 'jupyterclient': ('http://jupyter-client.readthedocs.io/en/latest/', None), | |
221 | 'ipyparallel': ('http://ipyparallel.readthedocs.io/en/latest/', None), |
|
223 | 'ipyparallel': ('http://ipyparallel.readthedocs.io/en/latest/', None), | |
222 | 'jupyter': ('http://jupyter.readthedocs.io/en/latest/', None), |
|
224 | 'jupyter': ('http://jupyter.readthedocs.io/en/latest/', None), | |
223 | } |
|
225 | } | |
224 |
|
226 | |||
225 | # Options for LaTeX output |
|
227 | # Options for LaTeX output | |
226 | # ------------------------ |
|
228 | # ------------------------ | |
227 |
|
229 | |||
228 | # The paper size ('letter' or 'a4'). |
|
230 | # The paper size ('letter' or 'a4'). | |
229 | latex_paper_size = 'letter' |
|
231 | latex_paper_size = 'letter' | |
230 |
|
232 | |||
231 | # The font size ('10pt', '11pt' or '12pt'). |
|
233 | # The font size ('10pt', '11pt' or '12pt'). | |
232 | latex_font_size = '11pt' |
|
234 | latex_font_size = '11pt' | |
233 |
|
235 | |||
234 | # Grouping the document tree into LaTeX files. List of tuples |
|
236 | # Grouping the document tree into LaTeX files. List of tuples | |
235 | # (source start file, target name, title, author, document class [howto/manual]). |
|
237 | # (source start file, target name, title, author, document class [howto/manual]). | |
236 |
|
238 | |||
237 | latex_documents = [ |
|
239 | latex_documents = [ | |
238 | ('index', 'ipython.tex', 'IPython Documentation', |
|
240 | ('index', 'ipython.tex', 'IPython Documentation', | |
239 | u"""The IPython Development Team""", 'manual', True), |
|
241 | u"""The IPython Development Team""", 'manual', True), | |
240 | ('parallel/winhpc_index', 'winhpc_whitepaper.tex', |
|
242 | ('parallel/winhpc_index', 'winhpc_whitepaper.tex', | |
241 | 'Using IPython on Windows HPC Server 2008', |
|
243 | 'Using IPython on Windows HPC Server 2008', | |
242 | u"Brian E. Granger", 'manual', True) |
|
244 | u"Brian E. Granger", 'manual', True) | |
243 | ] |
|
245 | ] | |
244 |
|
246 | |||
245 | # The name of an image file (relative to this directory) to place at the top of |
|
247 | # The name of an image file (relative to this directory) to place at the top of | |
246 | # the title page. |
|
248 | # the title page. | |
247 | #latex_logo = None |
|
249 | #latex_logo = None | |
248 |
|
250 | |||
249 | # For "manual" documents, if this is true, then toplevel headings are parts, |
|
251 | # For "manual" documents, if this is true, then toplevel headings are parts, | |
250 | # not chapters. |
|
252 | # not chapters. | |
251 | #latex_use_parts = False |
|
253 | #latex_use_parts = False | |
252 |
|
254 | |||
253 | # Additional stuff for the LaTeX preamble. |
|
255 | # Additional stuff for the LaTeX preamble. | |
254 | #latex_preamble = '' |
|
256 | #latex_preamble = '' | |
255 |
|
257 | |||
256 | # Documents to append as an appendix to all manuals. |
|
258 | # Documents to append as an appendix to all manuals. | |
257 | #latex_appendices = [] |
|
259 | #latex_appendices = [] | |
258 |
|
260 | |||
259 | # If false, no module index is generated. |
|
261 | # If false, no module index is generated. | |
260 | latex_use_modindex = True |
|
262 | latex_use_modindex = True | |
261 |
|
263 | |||
262 |
|
264 | |||
263 | # Options for texinfo output |
|
265 | # Options for texinfo output | |
264 | # -------------------------- |
|
266 | # -------------------------- | |
265 |
|
267 | |||
266 | texinfo_documents = [ |
|
268 | texinfo_documents = [ | |
267 | (master_doc, 'ipython', 'IPython Documentation', |
|
269 | (master_doc, 'ipython', 'IPython Documentation', | |
268 | 'The IPython Development Team', |
|
270 | 'The IPython Development Team', | |
269 | 'IPython', |
|
271 | 'IPython', | |
270 | 'IPython Documentation', |
|
272 | 'IPython Documentation', | |
271 | 'Programming', |
|
273 | 'Programming', | |
272 | 1), |
|
274 | 1), | |
273 | ] |
|
275 | ] | |
274 |
|
276 | |||
275 | modindex_common_prefix = ['IPython.'] |
|
277 | modindex_common_prefix = ['IPython.'] | |
276 |
|
278 | |||
277 |
|
279 | |||
278 | # Cleanup |
|
280 | # Cleanup | |
279 | # ------- |
|
281 | # ------- | |
280 | # delete release info to avoid pickling errors from sphinx |
|
282 | # delete release info to avoid pickling errors from sphinx | |
281 |
|
283 | |||
282 | del iprelease |
|
284 | del iprelease |
@@ -1,193 +1,193 b'' | |||||
1 | .. _release_process: |
|
1 | .. _release_process: | |
2 |
|
2 | |||
3 | ======================= |
|
3 | ======================= | |
4 | IPython release process |
|
4 | IPython release process | |
5 | ======================= |
|
5 | ======================= | |
6 |
|
6 | |||
7 | This document contains the process that is used to create an IPython release. |
|
7 | This document contains the process that is used to create an IPython release. | |
8 |
|
8 | |||
9 | Conveniently, the `release` script in the `tools` directory of the `IPython` |
|
9 | Conveniently, the `release` script in the `tools` directory of the `IPython` | |
10 | repository automates most of the release process. This document serves as a |
|
10 | repository automates most of the release process. This document serves as a | |
11 | handy reminder and checklist for the release manager. |
|
11 | handy reminder and checklist for the release manager. | |
12 |
|
12 | |||
13 | 1. Set Environment variables |
|
13 | 1. Set Environment variables | |
14 | ---------------------------- |
|
14 | ---------------------------- | |
15 |
|
15 | |||
16 | Set environment variables to document previous release tag, current |
|
16 | Set environment variables to document previous release tag, current | |
17 | release milestone, current release version, and git tag:: |
|
17 | release milestone, current release version, and git tag:: | |
18 |
|
18 | |||
19 | PREV_RELEASE=4.0.0 |
|
19 | PREV_RELEASE=4.0.0 | |
20 | MILESTONE=4.1 |
|
20 | MILESTONE=4.1 | |
21 | VERSION=4.1.0 |
|
21 | VERSION=4.1.0 | |
22 | BRANCH=master |
|
22 | BRANCH=master | |
23 |
|
23 | |||
24 | These variables may be used later to copy/paste as answers to the script |
|
24 | These variables may be used later to copy/paste as answers to the script | |
25 | questions instead of typing the appropriate command when the time comes. These |
|
25 | questions instead of typing the appropriate command when the time comes. These | |
26 | variables are not used by the scripts directly; therefore, there is no need to |
|
26 | variables are not used by the scripts directly; therefore, there is no need to | |
27 | `export` the variables. |
|
27 | `export` the variables. | |
28 |
|
28 | |||
29 | 2. Create GitHub stats and finish release note |
|
29 | 2. Create GitHub stats and finish release note | |
30 | ---------------------------------------------- |
|
30 | ---------------------------------------------- | |
31 |
|
31 | |||
32 | .. note:: |
|
32 | .. note:: | |
33 |
|
33 | |||
34 | Before generating the GitHub stats, verify that all closed issues and |
|
34 | Before generating the GitHub stats, verify that all closed issues and | |
35 | pull requests have `appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_. |
|
35 | pull requests have `appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_. | |
36 | `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_ |
|
36 | `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_ | |
37 | should return no results before creating the GitHub stats. |
|
37 | should return no results before creating the GitHub stats. | |
38 |
|
38 | |||
39 | If a major release: |
|
39 | If a major release: | |
40 |
|
40 | |||
41 | - merge any pull request notes into what's new:: |
|
41 | - merge any pull request notes into what's new:: | |
42 |
|
42 | |||
43 | python tools/update_whatsnew.py |
|
43 | python tools/update_whatsnew.py | |
44 |
|
44 | |||
45 | - update `docs/source/whatsnew/development.rst`, to ensure it covers |
|
45 | - update `docs/source/whatsnew/development.rst`, to ensure it covers | |
46 | the major release features |
|
46 | the major release features | |
47 | - move the contents of `development.rst` to `versionX.rst` where `X` is |
|
47 | - move the contents of `development.rst` to `versionX.rst` where `X` is | |
48 | the numerical release version |
|
48 | the numerical release version | |
49 | - generate summary of GitHub contributions, which can be done with:: |
|
49 | - generate summary of GitHub contributions, which can be done with:: | |
50 |
|
50 | |||
51 | python tools/github_stats.py --milestone $MILESTONE > stats.rst |
|
51 | python tools/github_stats.py --milestone $MILESTONE > stats.rst | |
52 |
|
52 | |||
53 | which may need some manual cleanup of `stats.rst`. Add the cleaned |
|
53 | which may need some manual cleanup of `stats.rst`. Add the cleaned | |
54 | `stats.rst` results to `docs/source/whatsnew/github-stats-X.rst` where |
|
54 | `stats.rst` results to `docs/source/whatsnew/github-stats-X.rst` where | |
55 | `X` is the numerical release version. If creating a major release, make |
|
55 | `X` is the numerical release version. If creating a major release, make | |
56 | a new `github-stats-X.rst` file; if creating a minor release, the |
|
56 | a new `github-stats-X.rst` file; if creating a minor release, the | |
57 | content from `stats.rst` may simply be added to the top of an existing |
|
57 | content from `stats.rst` may simply be added to the top of an existing | |
58 | `github-stats-X.rst` file. |
|
58 | `github-stats-X.rst` file. | |
59 |
|
59 | |||
60 | To find duplicates and update `.mailmap`, use:: |
|
60 | To find duplicates and update `.mailmap`, use:: | |
61 |
|
61 | |||
62 | git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f |
|
62 | git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f | |
63 |
|
63 | |||
64 | 3. Make sure the repository is clean |
|
64 | 3. Make sure the repository is clean | |
65 | ------------------------------------ |
|
65 | ------------------------------------ | |
66 |
|
66 | |||
67 | of any file that could be problematic. |
|
67 | of any file that could be problematic. | |
68 | Remove all non-tracked files with: |
|
68 | Remove all non-tracked files with: | |
69 |
|
69 | |||
70 | .. code:: |
|
70 | .. code:: | |
71 |
|
71 | |||
72 | git clean -xfdi |
|
72 | git clean -xfdi | |
73 |
|
73 | |||
74 | This will ask for confirmation before removing all untracked files. Make |
|
74 | This will ask for confirmation before removing all untracked files. Make | |
75 | sure the ``dist/`` folder is clean to avoid any stale builds from |
|
75 | sure the ``dist/`` folder is clean to avoid any stale builds from | |
76 | previous build attempts. |
|
76 | previous build attempts. | |
77 |
|
77 | |||
78 |
|
78 | |||
79 | 4. Update the release version number |
|
79 | 4. Update the release version number | |
80 | ------------------------------------ |
|
80 | ------------------------------------ | |
81 |
|
81 | |||
82 | Edit `IPython/core/release.py` to have the current version. |
|
82 | Edit `IPython/core/release.py` to have the current version. | |
83 |
|
83 | |||
84 | in particular, update version number and ``_version_extra`` content in |
|
84 | in particular, update version number and ``_version_extra`` content in | |
85 | ``IPython/core/release.py``. |
|
85 | ``IPython/core/release.py``. | |
86 |
|
86 | |||
87 | Make sure the version number matches pep440, in particular, `rc` and `beta` are |
|
87 | Make sure the version number matches pep440, in particular, `rc` and `beta` are | |
88 | not separated by `.` or the `sdist` and `bdist` will appear as different |
|
88 | not separated by `.` or the `sdist` and `bdist` will appear as different | |
89 | releases. For example, a valid version number for a release candidate (rc) |
|
89 | releases. For example, a valid version number for a release candidate (rc) | |
90 | release is: ``1.3rc1``. Notice that there is no separator between the '3' and |
|
90 | 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 `develop |
|
94 | Comment remove the `development` entry in `whatsnew/index.rst`. TODO, figure | |
95 | out how to make that automatic. |
|
95 | out how to make that automatic. | |
96 |
|
96 | |||
97 | 5. Run the `tools/build_release` script |
|
97 | 5. Run the `tools/build_release` script | |
98 | --------------------------------------- |
|
98 | --------------------------------------- | |
99 |
|
99 | |||
100 | Running `tools/build_release` does all the file checking and building that |
|
100 | Running `tools/build_release` does all the file checking and building that | |
101 | the real release script will do. This makes test installations, checks that |
|
101 | the real release script will do. This makes test installations, checks that | |
102 | the build procedure runs OK, and tests other steps in the release process. |
|
102 | the build procedure runs OK, and tests other steps in the release process. | |
103 |
|
103 | |||
104 | The `build_release` script will in particular verify that the version number |
|
104 | The `build_release` script will in particular verify that the version number | |
105 | match PEP 440, in order to avoid surprise at the time of build upload. |
|
105 | match PEP 440, in order to avoid surprise at the time of build upload. | |
106 |
|
106 | |||
107 | We encourage creating a test build of the docs as well. |
|
107 | We encourage creating a test build of the docs as well. | |
108 |
|
108 | |||
109 | 6. Create and push the new tag |
|
109 | 6. Create and push the new tag | |
110 | ------------------------------ |
|
110 | ------------------------------ | |
111 |
|
111 | |||
112 | Commit the changes to release.py:: |
|
112 | Commit the changes to release.py:: | |
113 |
|
113 | |||
114 | git commit -am "release $VERSION" |
|
114 | git commit -am "release $VERSION" | |
115 | git push origin $BRANCH |
|
115 | git push origin $BRANCH | |
116 |
|
116 | |||
117 | Create and push the tag:: |
|
117 | Create and push the tag:: | |
118 |
|
118 | |||
119 | git tag -am "release $VERSION" "$VERSION" |
|
119 | git tag -am "release $VERSION" "$VERSION" | |
120 | git push origin --tags |
|
120 | git push origin --tags | |
121 |
|
121 | |||
122 | Update release.py back to `x.y-dev` or `x.y-maint`, and re-add the |
|
122 | Update release.py back to `x.y-dev` or `x.y-maint`, and re-add the | |
123 |
`develop |
|
123 | `development` entry in `docs/source/whatsnew/index.rst` and push:: | |
124 |
|
124 | |||
125 | git commit -am "back to development" |
|
125 | git commit -am "back to development" | |
126 | git push origin $BRANCH |
|
126 | git push origin $BRANCH | |
127 |
|
127 | |||
128 | 7. Get a fresh clone |
|
128 | 7. Get a fresh clone | |
129 | -------------------- |
|
129 | -------------------- | |
130 |
|
130 | |||
131 | Get a fresh clone of the tag for building the release:: |
|
131 | Get a fresh clone of the tag for building the release:: | |
132 |
|
132 | |||
133 | cd /tmp |
|
133 | cd /tmp | |
134 | git clone --depth 1 https://github.com/ipython/ipython.git -b "$VERSION" |
|
134 | git clone --depth 1 https://github.com/ipython/ipython.git -b "$VERSION" | |
135 |
|
135 | |||
136 | 8. Run the release script |
|
136 | 8. Run the release script | |
137 | ------------------------- |
|
137 | ------------------------- | |
138 |
|
138 | |||
139 | Run the `release` script, this step requires having a current wheel, Python >=3.4 and Python 2.7.:: |
|
139 | Run the `release` script, this step requires having a current wheel, Python >=3.4 and Python 2.7.:: | |
140 |
|
140 | |||
141 | cd tools && ./release |
|
141 | cd tools && ./release | |
142 |
|
142 | |||
143 | This makes the tarballs, zipfiles, and wheels, and put them under the `dist/` |
|
143 | This makes the tarballs, zipfiles, and wheels, and put them under the `dist/` | |
144 | folder. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading |
|
144 | folder. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading | |
145 | them to PyPI. |
|
145 | them to PyPI. | |
146 |
|
146 | |||
147 | Use the following to actually upload the result of the build: |
|
147 | Use the following to actually upload the result of the build: | |
148 |
|
148 | |||
149 | ./release upload |
|
149 | ./release upload | |
150 |
|
150 | |||
151 | It should posts them to ``archive.ipython.org`` and registers the release |
|
151 | It should posts them to ``archive.ipython.org`` and registers the release | |
152 | with PyPI if you have the various authorisations. |
|
152 | with PyPI if you have the various authorisations. | |
153 |
|
153 | |||
154 | You might need to use `twine <https://github.com/pypa/twine>`_ (`twine upload |
|
154 | You might need to use `twine <https://github.com/pypa/twine>`_ (`twine upload | |
155 | dist/*`) manually to actually upload on PyPI. Unlike setuptools, twine is able |
|
155 | dist/*`) manually to actually upload on PyPI. Unlike setuptools, twine is able | |
156 | to upload packages over SSL. |
|
156 | to upload packages over SSL. | |
157 |
|
157 | |||
158 |
|
158 | |||
159 | 9. Draft a short release announcement |
|
159 | 9. Draft a short release announcement | |
160 | ------------------------------------- |
|
160 | ------------------------------------- | |
161 |
|
161 | |||
162 | The announcement should include: |
|
162 | The announcement should include: | |
163 |
|
163 | |||
164 | - release highlights |
|
164 | - release highlights | |
165 | - a link to the html version of the *What's new* section of the documentation |
|
165 | - a link to the html version of the *What's new* section of the documentation | |
166 | - a link to upgrade or installation tips (if necessary) |
|
166 | - a link to upgrade or installation tips (if necessary) | |
167 |
|
167 | |||
168 | Post the announcement to the mailing list and or blog, and link from Twitter. |
|
168 | Post the announcement to the mailing list and or blog, and link from Twitter. | |
169 |
|
169 | |||
170 | 10. Update milestones on GitHub |
|
170 | 10. Update milestones on GitHub | |
171 | ------------------------------- |
|
171 | ------------------------------- | |
172 |
|
172 | |||
173 | These steps will bring milestones up to date: |
|
173 | These steps will bring milestones up to date: | |
174 |
|
174 | |||
175 | - close the just released milestone |
|
175 | - close the just released milestone | |
176 | - open a new milestone for the next release (x, y+1), if the milestone doesn't |
|
176 | - open a new milestone for the next release (x, y+1), if the milestone doesn't | |
177 | exist already |
|
177 | exist already | |
178 |
|
178 | |||
179 | 11. Update the IPython website |
|
179 | 11. Update the IPython website | |
180 | ------------------------------ |
|
180 | ------------------------------ | |
181 |
|
181 | |||
182 | The IPython website should document the new release: |
|
182 | The IPython website should document the new release: | |
183 |
|
183 | |||
184 | - add release announcement (news, announcements) |
|
184 | - add release announcement (news, announcements) | |
185 | - update current version and download links |
|
185 | - update current version and download links | |
186 | - update links on the documentation page (especially if a major release) |
|
186 | - update links on the documentation page (especially if a major release) | |
187 |
|
187 | |||
188 | 12. Celebrate! |
|
188 | 12. Celebrate! | |
189 | -------------- |
|
189 | -------------- | |
190 |
|
190 | |||
191 | Celebrate the release and please thank the contributors for their work. Great |
|
191 | Celebrate the release and please thank the contributors for their work. Great | |
192 | job! |
|
192 | job! | |
193 |
|
193 |
@@ -1,110 +1,111 b'' | |||||
1 | .. _introduction: |
|
1 | .. _introduction: | |
2 |
|
2 | |||
3 | ===================== |
|
3 | ===================== | |
4 | IPython Documentation |
|
4 | IPython Documentation | |
5 | ===================== |
|
5 | ===================== | |
6 |
|
6 | |||
7 | .. htmlonly:: |
|
7 | .. htmlonly:: | |
8 |
|
8 | |||
9 | :Release: |release| |
|
9 | :Release: |release| | |
10 | :Date: |today| |
|
10 | :Date: |today| | |
11 |
|
11 | |||
12 | Welcome to the official IPython documentation |
|
12 | Welcome to the official IPython documentation | |
13 |
|
13 | |||
14 | IPython provides a rich toolkit to help you make the most out of using Python |
|
14 | IPython provides a rich toolkit to help you make the most out of using Python | |
15 | interactively. Its main components are: |
|
15 | interactively. Its main components are: | |
16 |
|
16 | |||
17 | * A powerful interactive Python shell |
|
17 | * A powerful interactive Python shell | |
|
18 | ||||
18 | * A `Jupyter <http://jupyter.org/>`_ kernel to work with Python code in Jupyter |
|
19 | * A `Jupyter <http://jupyter.org/>`_ kernel to work with Python code in Jupyter | |
19 | notebooks and other interactive frontends. |
|
20 | notebooks and other interactive frontends. | |
20 |
|
21 | |||
21 | The enhanced interactive Python shells and kernel have the following main |
|
22 | The enhanced interactive Python shells and kernel have the following main | |
22 | features: |
|
23 | features: | |
23 |
|
24 | |||
24 | * Comprehensive object introspection. |
|
25 | * Comprehensive object introspection. | |
25 |
|
26 | |||
26 | * Input history, persistent across sessions. |
|
27 | * Input history, persistent across sessions. | |
27 |
|
28 | |||
28 | * Caching of output results during a session with automatically generated |
|
29 | * Caching of output results during a session with automatically generated | |
29 | references. |
|
30 | references. | |
30 |
|
31 | |||
31 | * Extensible tab completion, with support by default for completion of python |
|
32 | * Extensible tab completion, with support by default for completion of python | |
32 | variables and keywords, filenames and function keywords. |
|
33 | variables and keywords, filenames and function keywords. | |
33 |
|
34 | |||
34 | * Extensible system of 'magic' commands for controlling the environment and |
|
35 | * Extensible system of 'magic' commands for controlling the environment and | |
35 | performing many tasks related either to IPython or the operating system. |
|
36 | performing many tasks related either to IPython or the operating system. | |
36 |
|
37 | |||
37 | * A rich configuration system with easy switching between different setups |
|
38 | * A rich configuration system with easy switching between different setups | |
38 | (simpler than changing $PYTHONSTARTUP environment variables every time). |
|
39 | (simpler than changing $PYTHONSTARTUP environment variables every time). | |
39 |
|
40 | |||
40 | * Session logging and reloading. |
|
41 | * Session logging and reloading. | |
41 |
|
42 | |||
42 | * Extensible syntax processing for special purpose situations. |
|
43 | * Extensible syntax processing for special purpose situations. | |
43 |
|
44 | |||
44 | * Access to the system shell with user-extensible alias system. |
|
45 | * Access to the system shell with user-extensible alias system. | |
45 |
|
46 | |||
46 | * Easily embeddable in other Python programs and GUIs. |
|
47 | * Easily embeddable in other Python programs and GUIs. | |
47 |
|
48 | |||
48 | * Integrated access to the pdb debugger and the Python profiler. |
|
49 | * Integrated access to the pdb debugger and the Python profiler. | |
49 |
|
50 | |||
50 |
|
51 | |||
51 | The Command line interface inherit all the above functionality and posses |
|
52 | The Command line interface inherit all the above functionality and posses | |
52 |
|
53 | |||
53 |
* real multiline edi |
|
54 | * real multi-line editing. | |
54 |
|
55 | |||
55 | * syntax highlighting as you type |
|
56 | * syntax highlighting as you type | |
56 |
|
57 | |||
57 |
* intgration with command line editor for a better workflow. |
|
58 | * integration with command line editor for a better workflow. | |
58 |
|
59 | |||
59 | The kernel also have its share of feature, when used with a compatible frontend |
|
60 | The kernel also have its share of feature, when used with a compatible frontend | |
60 | it allows for: |
|
61 | it allows for: | |
61 |
|
62 | |||
62 | * rich display system for object allowing to display Html, Images, Latex,Sounds |
|
63 | * rich display system for object allowing to display Html, Images, Latex,Sounds | |
63 | Video. |
|
64 | Video. | |
64 |
|
65 | |||
65 |
* interactive widgets with the use of the ``ipywigets`` package. |
|
66 | * interactive widgets with the use of the ``ipywidgets`` package. | |
66 |
|
67 | |||
67 |
|
68 | |||
68 | This documentation will walk through most of the features of the IPython |
|
69 | 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 | command line and kernel, as well as describe the internals mechanisms in order | |
70 | to improve your Python workflow. |
|
71 | to improve your Python workflow. | |
71 |
|
72 | |||
72 | You can always find the table of content for this documentation in the left |
|
73 | 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 | sidebar, allowing you to come back on previous section if needed, or skip ahead. | |
74 |
|
75 | |||
75 |
|
76 | |||
76 | The latest development version is always available from IPython's `GitHub |
|
77 | The latest development version is always available from IPython's `GitHub | |
77 | repository <http://github.com/ipython/ipython>`_. |
|
78 | repository <http://github.com/ipython/ipython>`_. | |
78 |
|
79 | |||
79 |
|
80 | |||
80 |
|
81 | |||
81 |
|
82 | |||
82 | .. toctree:: |
|
83 | .. toctree:: | |
83 | :maxdepth: 1 |
|
84 | :maxdepth: 1 | |
84 | :hidden: |
|
85 | :hidden: | |
85 |
|
86 | |||
86 | self |
|
87 | self | |
87 | overview |
|
88 | overview | |
88 | whatsnew/index |
|
89 | whatsnew/index | |
89 | install/index |
|
90 | install/index | |
90 | interactive/index |
|
91 | interactive/index | |
91 | config/index |
|
92 | config/index | |
92 | development/index |
|
93 | development/index | |
93 | coredev/index |
|
94 | coredev/index | |
94 | api/index |
|
95 | api/index | |
95 | about/index |
|
96 | about/index | |
96 |
|
97 | |||
97 | .. seealso:: |
|
98 | .. seealso:: | |
98 |
|
99 | |||
99 | `Jupyter documentation <http://jupyter.readthedocs.io/en/latest/>`__ |
|
100 | `Jupyter documentation <http://jupyter.readthedocs.io/en/latest/>`__ | |
100 | The Notebook code and many other pieces formerly in IPython are now parts |
|
101 | The Notebook code and many other pieces formerly in IPython are now parts | |
101 | of Project Jupyter. |
|
102 | of Project Jupyter. | |
102 | `ipyparallel documentation <http://ipyparallel.readthedocs.io/en/latest/>`__ |
|
103 | `ipyparallel documentation <http://ipyparallel.readthedocs.io/en/latest/>`__ | |
103 | Formerly ``IPython.parallel``. |
|
104 | Formerly ``IPython.parallel``. | |
104 |
|
105 | |||
105 |
|
106 | |||
106 | .. htmlonly:: |
|
107 | .. htmlonly:: | |
107 | * :ref:`genindex` |
|
108 | * :ref:`genindex` | |
108 | * :ref:`modindex` |
|
109 | * :ref:`modindex` | |
109 | * :ref:`search` |
|
110 | * :ref:`search` | |
110 |
|
111 |
@@ -1,60 +1,58 b'' | |||||
1 | .. _install_index: |
|
1 | .. _install_index: | |
2 |
|
2 | |||
3 | ============ |
|
3 | ============ | |
4 | Installation |
|
4 | Installation | |
5 | ============ |
|
5 | ============ | |
6 |
|
6 | |||
7 | .. toctree:: |
|
7 | .. toctree:: | |
8 | :maxdepth: 3 |
|
8 | :maxdepth: 3 | |
9 | :hidden: |
|
9 | :hidden: | |
10 |
|
10 | |||
11 |
|
11 | |||
12 | install |
|
12 | install | |
13 | kernel_install |
|
13 | kernel_install | |
14 |
|
14 | |||
15 |
|
15 | |||
16 |
|
16 | |||
17 |
This sections will guide you |
|
17 | This sections will guide you through `installing IPython itself <install>`_, and | |
18 |
installing `kernels for |
|
18 | installing `kernels for Jupyter <kernel_install>`_ if you wish to work with | |
19 |
multiple version of Python, or multiple environments. |
|
19 | multiple version of Python, or multiple environments. | |
20 |
|
20 | |||
21 | To know more, head to the next section. |
|
|||
22 |
|
||||
23 |
|
21 | |||
24 | Quick install reminder |
|
22 | Quick install reminder | |
25 | ~~~~~~~~~~~~~~~~~~~~~~ |
|
23 | ~~~~~~~~~~~~~~~~~~~~~~ | |
26 |
|
24 | |||
27 |
Here is a quick reminder of the |
|
25 | Here is a quick reminder of the commands needed for installation if you are | |
28 | familiar with IPython and are just searching to refresh your memory: |
|
26 | already familiar with IPython and are just searching to refresh your memory: | |
29 |
|
27 | |||
30 | Install IPython: |
|
28 | Install IPython: | |
31 |
|
29 | |||
32 | .. code-block:: bash |
|
30 | .. code-block:: bash | |
33 |
|
31 | |||
34 | $ pip install ipython |
|
32 | $ pip install ipython | |
35 |
|
33 | |||
36 |
|
34 | |||
37 | Install and register an IPython kernel with Jupyter: |
|
35 | Install and register an IPython kernel with Jupyter: | |
38 |
|
36 | |||
39 |
|
37 | |||
40 | .. code-block:: bash |
|
38 | .. code-block:: bash | |
41 |
|
39 | |||
42 | $ python -m pip install ipykernel |
|
40 | $ python -m pip install ipykernel | |
43 |
|
41 | |||
44 | $ python -m ipykernel install [--user] [--name <machine-readable-name>] [--display-name <"User Friendly Name">] |
|
42 | $ python -m ipykernel install [--user] [--name <machine-readable-name>] [--display-name <"User Friendly Name">] | |
45 |
|
43 | |||
46 | for more help see |
|
44 | for more help see | |
47 |
|
45 | |||
48 | .. code-block:: bash |
|
46 | .. code-block:: bash | |
49 |
|
47 | |||
50 | $ python -m ipykernel install --help |
|
48 | $ python -m ipykernel install --help | |
51 |
|
49 | |||
52 |
|
50 | |||
53 |
|
51 | |||
54 | .. seealso:: |
|
52 | .. seealso:: | |
55 |
|
53 | |||
56 | `Installing Jupyter <http://jupyter.readthedocs.io/en/latest/install.html>`__ |
|
54 | `Installing Jupyter <http://jupyter.readthedocs.io/en/latest/install.html>`__ | |
57 | The Notebook, nbconvert, and many other former pieces of IPython are now |
|
55 | The Notebook, nbconvert, and many other former pieces of IPython are now | |
58 | part of Project Jupyter. |
|
56 | part of Project Jupyter. | |
59 |
|
57 | |||
60 |
|
58 |
@@ -1,131 +1,132 b'' | |||||
1 | Installing IPython |
|
1 | Installing IPython | |
2 | ================== |
|
2 | ================== | |
3 |
|
3 | |||
4 |
|
4 | |||
5 | IPython requires Python 2.7 or β₯ 3.3. |
|
5 | IPython requires Python 2.7 or β₯ 3.3. | |
6 |
|
6 | |||
7 |
|
7 | |||
8 | Quick Install |
|
8 | Quick Install | |
9 | ------------- |
|
9 | ------------- | |
10 |
|
10 | |||
11 | With ``pip`` already installed : |
|
11 | With ``pip`` already installed : | |
12 |
|
12 | |||
13 | .. code-block:: bash |
|
13 | .. code-block:: bash | |
14 |
|
14 | |||
15 | $ pip install ipython |
|
15 | $ pip install ipython | |
16 |
|
16 | |||
17 |
This |
|
17 | This installs IPython as well as its dependencies. | |
18 |
|
18 | |||
19 |
If you t |
|
19 | If you want to use IPython with notebooks or the Qt console, you should also | |
20 | ``jupyter``. |
|
20 | install Jupyter ``pip install jupyter``. | |
21 |
|
21 | |||
22 |
|
22 | |||
23 |
|
23 | |||
24 | Overview |
|
24 | Overview | |
25 | -------- |
|
25 | -------- | |
26 |
|
26 | |||
27 | This document describes in detail the steps required to install IPython. |
|
27 | This document describes in detail the steps required to install IPython. | |
28 | 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, | |
29 | see `the install page <http://ipython.org/install.html>`_ of the IPython website. |
|
29 | see `the install page <http://ipython.org/install.html>`_ of the IPython website. | |
30 |
|
30 | |||
31 | 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. | |
32 |
|
32 | |||
33 | IPython and most dependencies should be installed via :command:`pip`. |
|
33 | IPython and most dependencies should be installed via :command:`pip`. | |
34 | 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. | |
35 | More information about :mod:`pip` can be found on |
|
35 | More information about :mod:`pip` can be found on | |
36 | `its PyPI page <https://pip.pypa.io>`__. |
|
36 | `its PyPI page <https://pip.pypa.io>`__. | |
37 |
|
37 | |||
38 |
|
38 | |||
39 | More general information about installing Python packages can be found in |
|
39 | More general information about installing Python packages can be found in | |
40 | `Python's documentation <http://docs.python.org>`_. |
|
40 | `Python's documentation <http://docs.python.org>`_. | |
41 |
|
41 | |||
42 |
|
42 | |||
43 | Installing IPython itself |
|
43 | Installing IPython itself | |
44 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
44 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
45 |
|
45 | |||
46 | IPython requires several dependencies to work correctly, it is not recommended |
|
46 | IPython requires several dependencies to work correctly, it is not recommended | |
47 |
to install IPython and all it |
|
47 | to install IPython and all its dependencies manually as this can be quite long and troublesome. | |
48 |
You should |
|
48 | You should use the python package manager ``pip``. | |
49 |
|
49 | |||
50 | Installation using pip |
|
50 | Installation using pip | |
51 | ~~~~~~~~~~~~~~~~~~~~~~ |
|
51 | ~~~~~~~~~~~~~~~~~~~~~~ | |
52 |
|
52 | |||
53 |
Make sure you have the latest version of :mod:`pip` ( |
|
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 |
|
54 | manager) installed. If you do not, head to `Pip documentation | |
55 |
<https://pip.pypa.io/en/stable/installing/>` |
|
55 | <https://pip.pypa.io/en/stable/installing/>`_ and install :mod:`pip` first. | |
56 |
|
56 | |||
57 | The quickest way to get up and running with IPython is to install it with pip: |
|
57 | The quickest way to get up and running with IPython is to install it with pip: | |
58 |
|
58 | |||
59 | .. code-block:: bash |
|
59 | .. code-block:: bash | |
60 |
|
60 | |||
61 | $ pip install ipython |
|
61 | $ pip install ipython | |
62 |
|
62 | |||
63 | That's it. |
|
63 | That's it. | |
64 |
|
64 | |||
65 |
|
65 | |||
66 | Installation from source |
|
66 | Installation from source | |
67 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
|
67 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
68 |
|
68 | |||
69 | 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, | |
70 | grab the latest stable tarball of IPython `from PyPI |
|
70 | grab the latest stable tarball of IPython `from PyPI | |
71 | <https://pypi.python.org/pypi/ipython>`__. Then do the following: |
|
71 | <https://pypi.python.org/pypi/ipython>`__. Then do the following: | |
72 |
|
72 | |||
73 | .. code-block:: bash |
|
73 | .. code-block:: bash | |
74 |
|
74 | |||
75 | $ tar -xzf ipython.tar.gz |
|
75 | $ tar -xzf ipython.tar.gz | |
76 | $ cd ipython |
|
76 | $ cd ipython | |
77 | $ pip install . |
|
77 | $ pip install . | |
78 |
|
78 | |||
79 | Do not invoke ``setup.py`` directly as this can have undesirable consequences for further upgrades. |
|
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. |
|
80 | Try to also avoid any usage of ``easy_install`` that can have similar undesirable consequences. | |
81 |
|
81 | |||
82 | 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 | |
83 | permissions, you may need to run the last command with :command:`sudo`. You can |
|
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 |
|
84 | also install in user specific location by using the ``--user`` flag in conjunction with pip. | |
85 |
|
85 | |||
86 |
To |
|
86 | To run IPython's test suite, use the :command:`iptest` command from outside of the IPython source tree: | |
87 |
|
87 | |||
88 | .. code-block:: bash |
|
88 | .. code-block:: bash | |
89 |
|
89 | |||
90 | $ iptest |
|
90 | $ iptest | |
91 |
|
91 | |||
92 |
|
92 | |||
93 | Installing the development version |
|
93 | Installing the development version | |
94 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
94 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
95 |
|
95 | |||
96 | 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 | |
97 | `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 | |
98 | need to have Git installed on your system. Then do: |
|
98 | need to have Git installed on your system. Then do: | |
99 |
|
99 | |||
100 | .. code-block:: bash |
|
100 | .. code-block:: bash | |
101 |
|
101 | |||
102 | $ git clone https://github.com/ipython/ipython.git |
|
102 | $ git clone https://github.com/ipython/ipython.git | |
103 | $ cd ipython |
|
103 | $ cd ipython | |
104 | $ pip install . |
|
104 | $ pip install . | |
105 |
|
105 | |||
106 | Some users want to be able to follow the development branch as it changes. |
|
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: |
|
107 | With :mod:`pip` installed, you can replace the last step by: | |
108 |
|
108 | |||
109 | .. code-block:: bash |
|
109 | .. code-block:: bash | |
110 |
|
110 | |||
111 | $ pip install -e . |
|
111 | $ pip install -e . | |
112 |
|
112 | |||
113 | 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 | |
114 | the appropriate location. |
|
114 | the appropriate location. | |
115 |
|
115 | |||
116 | 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: | |
117 |
|
117 | |||
118 | .. code-block:: bash |
|
118 | .. code-block:: bash | |
119 |
|
119 | |||
120 | $ git pull |
|
120 | $ git pull | |
121 |
|
121 | |||
122 | .. _dependencies: |
|
122 | .. _dependencies: | |
123 |
|
123 | |||
124 | Dependencies |
|
124 | Dependencies | |
125 | ~~~~~~~~~~~~ |
|
125 | ~~~~~~~~~~~~ | |
126 |
|
126 | |||
127 | 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 | |
128 | 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 | |
129 | 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. | |
130 | They're not listed here, because they may change from release to release, and |
|
130 | They're not listed here since a static list would inevitably fall out of date as | |
131 | depending on platform so a static list will inevitably get out of date. |
|
131 | dependencies may change from release to release and also vary depending on | |
|
132 | the platform. |
@@ -1,296 +1,296 b'' | |||||
1 | .. _overview: |
|
1 | .. _overview: | |
2 |
|
2 | |||
3 | ======== |
|
3 | ======== | |
4 | Overview |
|
4 | Overview | |
5 | ======== |
|
5 | ======== | |
6 |
|
6 | |||
7 | One of Python's most useful features is its interactive interpreter. |
|
7 | One of Python's most useful features is its interactive interpreter. | |
8 | It allows for very fast testing of ideas without the overhead of |
|
8 | It allows for very fast testing of ideas without the overhead of | |
9 | creating test files as is typical in most programming languages. |
|
9 | creating test files as is typical in most programming languages. | |
10 | However, the interpreter supplied with the standard Python distribution |
|
10 | However, the interpreter supplied with the standard Python distribution | |
11 | is somewhat limited for extended interactive use. |
|
11 | is somewhat limited for extended interactive use. | |
12 |
|
12 | |||
13 | The goal of IPython is to create a comprehensive environment for |
|
13 | The goal of IPython is to create a comprehensive environment for | |
14 | interactive and exploratory computing. To support this goal, IPython |
|
14 | interactive and exploratory computing. To support this goal, IPython | |
15 | has three main components: |
|
15 | has three main components: | |
16 |
|
16 | |||
17 | * An enhanced interactive Python shell. |
|
17 | * An enhanced interactive Python shell. | |
18 |
|
18 | |||
19 | * A decoupled :ref:`two-process communication model <ipythonzmq>`, which |
|
19 | * A decoupled :ref:`two-process communication model <ipythonzmq>`, which | |
20 | 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 | |
21 | the web-based notebook provided with `Jupyter <https://jupyter.org>`_. |
|
21 | the web-based notebook provided with `Jupyter <https://jupyter.org>`_. | |
22 |
|
22 | |||
23 | * An architecture for interactive parallel computing now part of the |
|
23 | * An architecture for interactive parallel computing now part of the | |
24 | `ipyparallel` package. |
|
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 | |||
28 | Enhanced interactive Python shell |
|
28 | Enhanced interactive Python shell | |
29 | ================================= |
|
29 | ================================= | |
30 |
|
30 | |||
31 | IPython's interactive shell (:command:`ipython`), has the following goals, |
|
31 | IPython's interactive shell (:command:`ipython`), has the following goals, | |
32 | amongst others: |
|
32 | amongst others: | |
33 |
|
33 | |||
34 | 1. Provide an interactive shell superior to Python's default. IPython |
|
34 | 1. Provide an interactive shell superior to Python's default. IPython | |
35 | has many features for tab-completion, object introspection, system shell |
|
35 | has many features for tab-completion, object introspection, system shell | |
36 | access, command history retrieval across sessions, and its own special |
|
36 | access, command history retrieval across sessions, and its own special | |
37 | command system for adding functionality when working interactively. It |
|
37 | command system for adding functionality when working interactively. It | |
38 | tries to be a very efficient environment both for Python code development |
|
38 | tries to be a very efficient environment both for Python code development | |
39 | and for exploration of problems using Python objects (in situations like |
|
39 | and for exploration of problems using Python objects (in situations like | |
40 | data analysis). |
|
40 | data analysis). | |
41 |
|
41 | |||
42 | 2. Serve as an embeddable, ready to use interpreter for your own |
|
42 | 2. Serve as an embeddable, ready to use interpreter for your own | |
43 | programs. An interactive IPython shell can be started with a single call |
|
43 | programs. An interactive IPython shell can be started with a single call | |
44 | from inside another program, providing access to the current namespace. |
|
44 | from inside another program, providing access to the current namespace. | |
45 | This can be very useful both for debugging purposes and for situations |
|
45 | This can be very useful both for debugging purposes and for situations | |
46 | where a blend of batch-processing and interactive exploration are needed. |
|
46 | where a blend of batch-processing and interactive exploration are needed. | |
47 |
|
47 | |||
48 | 3. Offer a flexible framework which can be used as the base |
|
48 | 3. Offer a flexible framework which can be used as the base | |
49 | environment for working with other systems, with Python as the underlying |
|
49 | environment for working with other systems, with Python as the underlying | |
50 | bridge language. Specifically scientific environments like Mathematica, |
|
50 | bridge language. Specifically scientific environments like Mathematica, | |
51 | IDL and Matlab inspired its design, but similar ideas can be |
|
51 | IDL and Matlab inspired its design, but similar ideas can be | |
52 | useful in many fields. |
|
52 | useful in many fields. | |
53 |
|
53 | |||
54 | 4. Allow interactive testing of threaded graphical toolkits. IPython |
|
54 | 4. Allow interactive testing of threaded graphical toolkits. IPython | |
55 | has support for interactive, non-blocking control of GTK, Qt, WX, GLUT, and |
|
55 | has support for interactive, non-blocking control of GTK, Qt, WX, GLUT, and | |
56 | OS X applications via special threading flags. The normal Python |
|
56 | OS X applications via special threading flags. The normal Python | |
57 | shell can only do this for Tkinter applications. |
|
57 | shell can only do this for Tkinter applications. | |
58 |
|
58 | |||
59 | Main features of the interactive shell |
|
59 | Main features of the interactive shell | |
60 | -------------------------------------- |
|
60 | -------------------------------------- | |
61 |
|
61 | |||
62 | * Dynamic object introspection. One can access docstrings, function |
|
62 | * Dynamic object introspection. One can access docstrings, function | |
63 | definition prototypes, source code, source files and other details |
|
63 | definition prototypes, source code, source files and other details | |
64 | of any object accessible to the interpreter with a single |
|
64 | of any object accessible to the interpreter with a single | |
65 | keystroke (:samp:`?`, and using :samp:`??` provides additional detail). |
|
65 | keystroke (:samp:`?`, and using :samp:`??` provides additional detail). | |
66 |
|
66 | |||
67 | * Searching through modules and namespaces with :samp:`*` wildcards, both |
|
67 | * Searching through modules and namespaces with :samp:`*` wildcards, both | |
68 | when using the :samp:`?` system and via the :samp:`%psearch` command. |
|
68 | when using the :samp:`?` system and via the :samp:`%psearch` command. | |
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 ``prompt_toolkit`` library. |
|
72 | current directory. This is supported via the ``prompt_toolkit`` library. | |
73 | Custom completers can be implemented easily for different purposes |
|
73 | Custom completers can be implemented easily for different purposes | |
74 | (system commands, magic arguments etc.) |
|
74 | (system commands, magic arguments etc.) | |
75 |
|
75 | |||
76 | * Numbered input/output prompts with command history (persistent |
|
76 | * Numbered input/output prompts with command history (persistent | |
77 | across sessions and tied to each profile), full searching in this |
|
77 | across sessions and tied to each profile), full searching in this | |
78 | history and caching of all input and output. |
|
78 | history and caching of all input and output. | |
79 |
|
79 | |||
80 | * User-extensible 'magic' commands. A set of commands prefixed with |
|
80 | * User-extensible 'magic' commands. A set of commands prefixed with | |
81 | :samp:`%` or :samp:`%%` is available for controlling IPython itself and provides |
|
81 | :samp:`%` or :samp:`%%` is available for controlling IPython itself and provides | |
82 | directory control, namespace information and many aliases to |
|
82 | directory control, namespace information and many aliases to | |
83 | common system shell commands. |
|
83 | common system shell commands. | |
84 |
|
84 | |||
85 | * Alias facility for defining your own system aliases. |
|
85 | * Alias facility for defining your own system aliases. | |
86 |
|
86 | |||
87 | * Complete system shell access. Lines starting with :samp:`!` are passed |
|
87 | * Complete system shell access. Lines starting with :samp:`!` are passed | |
88 | directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd` |
|
88 | directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd` | |
89 | captures shell output into python variables for further use. |
|
89 | captures shell output into python variables for further use. | |
90 |
|
90 | |||
91 | * The ability to expand python variables when calling the system shell. In a |
|
91 | * The ability to expand python variables when calling the system shell. In a | |
92 | shell command, any python variable prefixed with :samp:`$` is expanded. A |
|
92 | shell command, any python variable prefixed with :samp:`$` is expanded. A | |
93 | double :samp:`$$` allows passing a literal :samp:`$` to the shell (for access |
|
93 | double :samp:`$$` allows passing a literal :samp:`$` to the shell (for access | |
94 | to shell and environment variables like :envvar:`PATH`). |
|
94 | to shell and environment variables like :envvar:`PATH`). | |
95 |
|
95 | |||
96 | * Filesystem navigation, via a magic :samp:`%cd` command, along with a |
|
96 | * Filesystem navigation, via a magic :samp:`%cd` command, along with a | |
97 | persistent bookmark system (using :samp:`%bookmark`) for fast access to |
|
97 | persistent bookmark system (using :samp:`%bookmark`) for fast access to | |
98 | frequently visited directories. |
|
98 | frequently visited directories. | |
99 |
|
99 | |||
100 | * A lightweight persistence framework via the :samp:`%store` command, which |
|
100 | * A lightweight persistence framework via the :samp:`%store` command, which | |
101 | allows you to save arbitrary Python variables. These get restored |
|
101 | allows you to save arbitrary Python variables. These get restored | |
102 | when you run the :samp:`%store -r` command. |
|
102 | when you run the :samp:`%store -r` command. | |
103 |
|
103 | |||
104 | * Automatic indentation and highlighting of code as you type (through the |
|
104 | * Automatic indentation and highlighting of code as you type (through the | |
105 | `prompt_toolkit` library). |
|
105 | `prompt_toolkit` library). | |
106 |
|
106 | |||
107 | * Macro system for quickly re-executing multiple lines of previous |
|
107 | * Macro system for quickly re-executing multiple lines of previous | |
108 | 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 | |
109 | stored persistently via :samp:`%store` and edited via :samp:`%edit`. |
|
109 | stored persistently via :samp:`%store` and edited via :samp:`%edit`. | |
110 |
|
110 | |||
111 | * Session logging (you can then later use these logs as code in your |
|
111 | * Session logging (you can then later use these logs as code in your | |
112 | programs). Logs can optionally timestamp all input, and also store |
|
112 | programs). Logs can optionally timestamp all input, and also store | |
113 | session output (marked as comments, so the log remains valid |
|
113 | session output (marked as comments, so the log remains valid | |
114 | Python source code). |
|
114 | Python source code). | |
115 |
|
115 | |||
116 | * Session restoring: logs can be replayed to restore a previous |
|
116 | * Session restoring: logs can be replayed to restore a previous | |
117 | session to the state where you left it. |
|
117 | session to the state where you left it. | |
118 |
|
118 | |||
119 | * Verbose and colored exception traceback printouts. Easier to parse |
|
119 | * Verbose and colored exception traceback printouts. Easier to parse | |
120 | visually, and in verbose mode they produce a lot of useful |
|
120 | visually, and in verbose mode they produce a lot of useful | |
121 | debugging information (basically a terminal version of the cgitb |
|
121 | debugging information (basically a terminal version of the cgitb | |
122 | module). |
|
122 | module). | |
123 |
|
123 | |||
124 | * Auto-parentheses via the :samp:`%autocall` command: callable objects can be |
|
124 | * Auto-parentheses via the :samp:`%autocall` command: callable objects can be | |
125 | executed without parentheses: :samp:`sin 3` is automatically converted to |
|
125 | executed without parentheses: :samp:`sin 3` is automatically converted to | |
126 | :samp:`sin(3)` |
|
126 | :samp:`sin(3)` | |
127 |
|
127 | |||
128 | * Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces |
|
128 | * Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces | |
129 | auto-quoting of the rest of the line: :samp:`,my_function a b` becomes |
|
129 | auto-quoting of the rest of the line: :samp:`,my_function a b` becomes | |
130 | automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b` |
|
130 | automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b` | |
131 | becomes :samp:`my_function("a b")`. |
|
131 | becomes :samp:`my_function("a b")`. | |
132 |
|
132 | |||
133 | * Extensible input syntax. You can define filters that pre-process |
|
133 | * Extensible input syntax. You can define filters that pre-process | |
134 | user input to simplify input in special situations. This allows |
|
134 | user input to simplify input in special situations. This allows | |
135 | for example pasting multi-line code fragments which start with |
|
135 | for example pasting multi-line code fragments which start with | |
136 | :samp:`>>>` or :samp:`...` such as those from other python sessions or the |
|
136 | :samp:`>>>` or :samp:`...` such as those from other python sessions or the | |
137 | standard Python documentation. |
|
137 | standard Python documentation. | |
138 |
|
138 | |||
139 | * Flexible :ref:`configuration system <config_overview>`. It uses a |
|
139 | * Flexible :ref:`configuration system <config_overview>`. It uses a | |
140 | configuration file which allows permanent setting of all command-line |
|
140 | configuration file which allows permanent setting of all command-line | |
141 | options, module loading, code and file execution. The system allows |
|
141 | options, module loading, code and file execution. The system allows | |
142 | recursive file inclusion, so you can have a base file with defaults and |
|
142 | recursive file inclusion, so you can have a base file with defaults and | |
143 | layers which load other customizations for particular projects. |
|
143 | layers which load other customizations for particular projects. | |
144 |
|
144 | |||
145 | * Embeddable. You can call IPython as a python shell inside your own |
|
145 | * Embeddable. You can call IPython as a python shell inside your own | |
146 | python programs. This can be used both for debugging code or for |
|
146 | python programs. This can be used both for debugging code or for | |
147 | providing interactive abilities to your programs with knowledge |
|
147 | providing interactive abilities to your programs with knowledge | |
148 | about the local namespaces (very useful in debugging and data |
|
148 | about the local namespaces (very useful in debugging and data | |
149 | analysis situations). |
|
149 | analysis situations). | |
150 |
|
150 | |||
151 | * Easy debugger access. You can set IPython to call up an enhanced version of |
|
151 | * Easy debugger access. You can set IPython to call up an enhanced version of | |
152 | the Python debugger (pdb) every time there is an uncaught exception. This |
|
152 | the Python debugger (pdb) every time there is an uncaught exception. This | |
153 | drops you inside the code which triggered the exception with all the data |
|
153 | drops you inside the code which triggered the exception with all the data | |
154 | live and it is possible to navigate the stack to rapidly isolate the source |
|
154 | live and it is possible to navigate the stack to rapidly isolate the source | |
155 | of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run |
|
155 | of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run | |
156 | any script under pdb's control, automatically setting initial breakpoints for |
|
156 | any script under pdb's control, automatically setting initial breakpoints for | |
157 | you. This version of pdb has IPython-specific improvements, including |
|
157 | you. This version of pdb has IPython-specific improvements, including | |
158 | tab-completion and traceback coloring support. For even easier debugger |
|
158 | tab-completion and traceback coloring support. For even easier debugger | |
159 | access, try :samp:`%debug` after seeing an exception. |
|
159 | access, try :samp:`%debug` after seeing an exception. | |
160 |
|
160 | |||
161 | * Profiler support. You can run single statements (similar to |
|
161 | * Profiler support. You can run single statements (similar to | |
162 | :samp:`profile.run()`) or complete programs under the profiler's control. |
|
162 | :samp:`profile.run()`) or complete programs under the profiler's control. | |
163 | While this is possible with standard cProfile or profile modules, |
|
163 | While this is possible with standard cProfile or profile modules, | |
164 | IPython wraps this functionality with magic commands (see :samp:`%prun` |
|
164 | IPython wraps this functionality with magic commands (see :samp:`%prun` | |
165 | and :samp:`%run -p`) convenient for rapid interactive work. |
|
165 | and :samp:`%run -p`) convenient for rapid interactive work. | |
166 |
|
166 | |||
167 | * Simple timing information. You can use the :samp:`%timeit` command to get |
|
167 | * Simple timing information. You can use the :samp:`%timeit` command to get | |
168 | the execution time of a Python statement or expression. This machinery is |
|
168 | the execution time of a Python statement or expression. This machinery is | |
169 | intelligent enough to do more repetitions for commands that finish very |
|
169 | intelligent enough to do more repetitions for commands that finish very | |
170 | quickly in order to get a better estimate of their running time. |
|
170 | quickly in order to get a better estimate of their running time. | |
171 |
|
171 | |||
172 | .. sourcecode:: ipython |
|
172 | .. sourcecode:: ipython | |
173 |
|
173 | |||
174 | In [1]: %timeit 1+1 |
|
174 | In [1]: %timeit 1+1 | |
175 | 10000000 loops, best of 3: 25.5 ns per loop |
|
175 | 10000000 loops, best of 3: 25.5 ns per loop | |
176 |
|
176 | |||
177 | In [2]: %timeit [math.sin(x) for x in range(5000)] |
|
177 | In [2]: %timeit [math.sin(x) for x in range(5000)] | |
178 | 1000 loops, best of 3: 719 Β΅s per loop |
|
178 | 1000 loops, best of 3: 719 Β΅s per loop | |
179 |
|
179 | |||
180 | .. |
|
180 | .. | |
181 |
|
181 | |||
182 | To get the timing information for more than one expression, use the |
|
182 | To get the timing information for more than one expression, use the | |
183 | :samp:`%%timeit` cell magic command. |
|
183 | :samp:`%%timeit` cell magic command. | |
184 |
|
184 | |||
185 |
|
185 | |||
186 | * Doctest support. The special :samp:`%doctest_mode` command toggles a mode |
|
186 | * Doctest support. The special :samp:`%doctest_mode` command toggles a mode | |
187 | to use doctest-compatible prompts, so you can use IPython sessions as |
|
187 | to use doctest-compatible prompts, so you can use IPython sessions as | |
188 | doctest code. By default, IPython also allows you to paste existing |
|
188 | doctest code. By default, IPython also allows you to paste existing | |
189 | doctests, and strips out the leading :samp:`>>>` and :samp:`...` prompts in |
|
189 | doctests, and strips out the leading :samp:`>>>` and :samp:`...` prompts in | |
190 | them. |
|
190 | them. | |
191 |
|
191 | |||
192 | .. _ipythonzmq: |
|
192 | .. _ipythonzmq: | |
193 |
|
193 | |||
194 | Decoupled two-process model |
|
194 | Decoupled two-process model | |
195 | ============================== |
|
195 | ============================== | |
196 |
|
196 | |||
197 | IPython has abstracted and extended the notion of a traditional |
|
197 | IPython has abstracted and extended the notion of a traditional | |
198 | *Read-Evaluate-Print Loop* (REPL) environment by decoupling the *evaluation* |
|
198 | *Read-Evaluate-Print Loop* (REPL) environment by decoupling the *evaluation* | |
199 | into its own process. We call this process a **kernel**: it receives execution |
|
199 | into its own process. We call this process a **kernel**: it receives execution | |
200 | instructions from clients and communicates the results back to them. |
|
200 | instructions from clients and communicates the results back to them. | |
201 |
|
201 | |||
202 | This decoupling allows us to have several clients connected to the same |
|
202 | This decoupling allows us to have several clients connected to the same | |
203 | 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. | |
204 | With the exclusion of the traditional single process terminal-based IPython |
|
204 | With the exclusion of the traditional single process terminal-based IPython | |
205 | (what you start if you run ``ipython`` without any subcommands), all |
|
205 | (what you start if you run ``ipython`` without any subcommands), all | |
206 | other IPython machinery uses this two-process model. Most of this is now part |
|
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 |
|
207 | of the `Jupyter` project, whis includes ``jupyter console``, ``jupyter | |
208 | qtconsole``, and ``jupyter notebook``. |
|
208 | qtconsole``, and ``jupyter notebook``. | |
209 |
|
209 | |||
210 | As an example, this means that when you start ``jupyter 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 | |
214 | which will skip initiating a new kernel and connect to the most recent kernel, |
|
214 | which will skip initiating a new kernel and connect to the most recent kernel, | |
215 | instead. To connect to a specific kernel once you have several kernels |
|
215 | instead. To connect to a specific kernel once you have several kernels | |
216 | running, use the ``%connect_info`` magic to get the unique connection file, |
|
216 | 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 `jupyter qtconsole |
|
220 | You can read more about using `jupyter qtconsole | |
221 | <http://jupyter.org/qtconsole/>`_, and |
|
221 | <http://jupyter.org/qtconsole/>`_, and | |
222 |
` |
|
222 | `jupyter 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 | |
224 | communication between kernels |
|
224 | communication between kernels | |
225 | and clients. |
|
225 | and clients. | |
226 |
|
226 | |||
227 | .. seealso:: |
|
227 | .. seealso:: | |
228 |
|
228 | |||
229 | `Frontend/Kernel Model`_ example notebook |
|
229 | `Frontend/Kernel Model`_ example notebook | |
230 |
|
230 | |||
231 |
|
231 | |||
232 | Interactive parallel computing |
|
232 | Interactive parallel computing | |
233 | ============================== |
|
233 | ============================== | |
234 |
|
234 | |||
235 | .. note:: |
|
235 | .. note:: | |
236 |
|
236 | |||
237 | This functionality is optional and now part of the `ipyparallel |
|
237 | This functionality is optional and now part of the `ipyparallel | |
238 | <http://ipyparallel.readthedocs.io/>`_ project. |
|
238 | <http://ipyparallel.readthedocs.io/>`_ project. | |
239 |
|
239 | |||
240 | Increasingly, parallel computer hardware, such as multicore CPUs, clusters and |
|
240 | Increasingly, parallel computer hardware, such as multicore CPUs, clusters and | |
241 | supercomputers, is becoming ubiquitous. Over the last several years, we have |
|
241 | supercomputers, is becoming ubiquitous. Over the last several years, we have | |
242 | 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 | |
243 | quickly and easily from Python. Moreover, this architecture is designed to |
|
243 | quickly and easily from Python. Moreover, this architecture is designed to | |
244 | support interactive and collaborative parallel computing. |
|
244 | support interactive and collaborative parallel computing. | |
245 |
|
245 | |||
246 | The main features of this system are: |
|
246 | The main features of this system are: | |
247 |
|
247 | |||
248 | * Quickly parallelize Python code from an interactive Python/IPython session. |
|
248 | * Quickly parallelize Python code from an interactive Python/IPython session. | |
249 |
|
249 | |||
250 | * A flexible and dynamic process model that be deployed on anything from |
|
250 | * A flexible and dynamic process model that be deployed on anything from | |
251 | multicore workstations to supercomputers. |
|
251 | multicore workstations to supercomputers. | |
252 |
|
252 | |||
253 | * An architecture that supports many different styles of parallelism, from |
|
253 | * An architecture that supports many different styles of parallelism, from | |
254 | message passing to task farming. And all of these styles can be handled |
|
254 | message passing to task farming. And all of these styles can be handled | |
255 | interactively. |
|
255 | interactively. | |
256 |
|
256 | |||
257 | * Both blocking and fully asynchronous interfaces. |
|
257 | * Both blocking and fully asynchronous interfaces. | |
258 |
|
258 | |||
259 | * High level APIs that enable many things to be parallelized in a few lines |
|
259 | * High level APIs that enable many things to be parallelized in a few lines | |
260 | of code. |
|
260 | of code. | |
261 |
|
261 | |||
262 | * Write parallel code that will run unchanged on everything from multicore |
|
262 | * Write parallel code that will run unchanged on everything from multicore | |
263 | workstations to supercomputers. |
|
263 | workstations to supercomputers. | |
264 |
|
264 | |||
265 | * Full integration with Message Passing libraries (MPI). |
|
265 | * Full integration with Message Passing libraries (MPI). | |
266 |
|
266 | |||
267 | * Capabilities based security model with full encryption of network connections. |
|
267 | * Capabilities based security model with full encryption of network connections. | |
268 |
|
268 | |||
269 | * Share live parallel jobs with other users securely. We call this |
|
269 | * Share live parallel jobs with other users securely. We call this | |
270 | collaborative parallel computing. |
|
270 | collaborative parallel computing. | |
271 |
|
271 | |||
272 | * Dynamically load balanced task farming system. |
|
272 | * Dynamically load balanced task farming system. | |
273 |
|
273 | |||
274 | * Robust error handling. Python exceptions raised in parallel execution are |
|
274 | * Robust error handling. Python exceptions raised in parallel execution are | |
275 | gathered and presented to the top-level code. |
|
275 | gathered and presented to the top-level code. | |
276 |
|
276 | |||
277 | For more information, see our :ref:`overview <parallel_index>` of using IPython |
|
277 | For more information, see our :ref:`overview <parallel_index>` of using IPython | |
278 | for parallel computing. |
|
278 | for parallel computing. | |
279 |
|
279 | |||
280 | Portability and Python requirements |
|
280 | Portability and Python requirements | |
281 | ----------------------------------- |
|
281 | ----------------------------------- | |
282 |
|
282 | |||
283 | As of the 2.0 release, IPython works with Python 2.7 and 3.3 or above. |
|
283 | As of the 2.0 release, IPython works with Python 2.7 and 3.3 or above. | |
284 | Version 1.0 additionally worked with Python 2.6 and 3.2. |
|
284 | Version 1.0 additionally worked with Python 2.6 and 3.2. | |
285 | Version 0.12 was the first version to fully support Python 3. |
|
285 | Version 0.12 was the first version to fully support Python 3. | |
286 |
|
286 | |||
287 | IPython is known to work on the following operating systems: |
|
287 | IPython is known to work on the following operating systems: | |
288 |
|
288 | |||
289 | * Linux |
|
289 | * Linux | |
290 | * Most other Unix-like OSs (AIX, Solaris, BSD, etc.) |
|
290 | * Most other Unix-like OSs (AIX, Solaris, BSD, etc.) | |
291 | * Mac OS X |
|
291 | * Mac OS X | |
292 | * Windows (CygWin, XP, Vista, etc.) |
|
292 | * Windows (CygWin, XP, Vista, etc.) | |
293 |
|
293 | |||
294 | See :ref:`here <install_index>` for instructions on how to install IPython. |
|
294 | See :ref:`here <install_index>` for instructions on how to install IPython. | |
295 |
|
295 | |||
296 | .. include:: links.txt |
|
296 | .. include:: links.txt |
@@ -1,164 +1,165 b'' | |||||
1 | ============ |
|
1 | ============ | |
2 | 5.x Series |
|
2 | 5.x Series | |
3 | ============ |
|
3 | ============ | |
4 |
|
4 | |||
5 | IPython 5.0 |
|
5 | IPython 5.0 | |
6 | =========== |
|
6 | =========== | |
7 |
|
7 | |||
8 | Released June, 2016 |
|
8 | Released June, 2016 | |
9 |
|
9 | |||
10 | IPython 5.0 now uses `prompt-toolkit` for the command line interface, thus |
|
10 | IPython 5.0 now uses `prompt-toolkit` for the command line interface, thus | |
11 | allowing real multi-line editing and syntactic coloration as you type. |
|
11 | allowing real multi-line editing and syntactic coloration as you type. | |
12 |
|
12 | |||
13 |
|
13 | |||
14 | When using IPython as a subprocess, like for emacs inferior-shell, IPython can |
|
14 | When using IPython as a subprocess, like for emacs inferior-shell, IPython can | |
15 | be started with --simple-prompt flag, which will bypass the prompt_toolkit |
|
15 | be started with --simple-prompt flag, which will bypass the prompt_toolkit | |
16 | input layer. In this mode completion, prompt color and many other features are |
|
16 | input layer. In this mode completion, prompt color and many other features are | |
17 | disabled. |
|
17 | disabled. | |
18 |
|
18 | |||
19 | Backwards incompatible changes |
|
19 | Backwards incompatible changes | |
20 | ------------------------------ |
|
20 | ------------------------------ | |
21 |
|
21 | |||
22 |
|
22 | |||
23 | The `install_ext magic` function which was deprecated since 4.0 have now been deleted. |
|
23 | The `install_ext magic` function which was deprecated since 4.0 have now been deleted. | |
24 | You can still distribute and install extension as packages on PyPI. |
|
24 | You can still distribute and install extension as packages on PyPI. | |
25 |
|
25 | |||
26 | Update IPython event triggering to ensure callback registration and |
|
26 | Update IPython event triggering to ensure callback registration and | |
27 | unregistration only affects the set of callbacks the *next* time that event is |
|
27 | unregistration only affects the set of callbacks the *next* time that event is | |
28 | triggered. See :ghissue:`9447` and :ghpull:`9453`. |
|
28 | triggered. See :ghissue:`9447` and :ghpull:`9453`. | |
29 |
|
29 | |||
30 | This is a change to the existing semantics, wherein one callback registering a |
|
30 | This is a change to the existing semantics, wherein one callback registering a | |
31 | second callback when triggered for an event would previously be invoked for |
|
31 | second callback when triggered for an event would previously be invoked for | |
32 | that same event. |
|
32 | that same event. | |
33 |
|
33 | |||
34 | Integration with pydb has been removed since pydb development has been stopped |
|
34 | Integration with pydb has been removed since pydb development has been stopped | |
35 | since 2012, and pydb is not installable from PyPI |
|
35 | since 2012, and pydb is not installable from PyPI | |
36 |
|
36 | |||
37 |
|
37 | |||
38 |
|
38 | |||
39 | Replacement of readline in TerminalInteractiveShell and PDB |
|
39 | Replacement of readline in TerminalInteractiveShell and PDB | |
40 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
40 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
41 |
|
41 | |||
42 | IPython 5.0 now uses ``prompt_toolkit``. The |
|
42 | IPython 5.0 now uses ``prompt_toolkit``. The | |
43 | ``IPython.terminal.interactiveshell.TerminalInteractiveShell`` now uses |
|
43 | ``IPython.terminal.interactiveshell.TerminalInteractiveShell`` now uses | |
44 | ``prompt_toolkit``. It is an almost complete rewrite, so many settings have |
|
44 | ``prompt_toolkit``. It is an almost complete rewrite, so many settings have | |
45 | thus changed or disappeared. The class keep the same name to avoid breaking |
|
45 | thus changed or disappeared. The class keep the same name to avoid breaking | |
46 | user configuration for the options which names is unchanged. |
|
46 | user configuration for the options which names is unchanged. | |
47 |
|
47 | |||
48 | The usage of ``prompt_toolkit`` is accompanied by a complete removal of all |
|
48 | The usage of ``prompt_toolkit`` is accompanied by a complete removal of all | |
49 | code, using ``readline``. A particular effect of not using `readline` anymore |
|
49 | code, using ``readline``. A particular effect of not using `readline` anymore | |
50 | is that `.inputrc` settings are note effective anymore. Options having similar |
|
50 | is that `.inputrc` settings are note effective anymore. Options having similar | |
51 | effects have likely been replaced by a configuration option on IPython itself |
|
51 | effects have likely been replaced by a configuration option on IPython itself | |
52 | (e.g: vi input mode). |
|
52 | (e.g: vi input mode). | |
53 |
|
53 | |||
54 | The `PromptManager` class have been removed, and the prompt machinery simplified. |
|
54 | The `PromptManager` class have been removed, and the prompt machinery simplified. | |
55 | See `TerminalInteractiveShell.prompts` configurable for how to setup your prompts. |
|
55 | See `TerminalInteractiveShell.prompts` configurable for how to setup your prompts. | |
56 |
|
56 | |||
57 | .. note:: |
|
57 | .. note:: | |
58 |
|
58 | |||
59 | During developement and beta cycle, ``TerminalInteractiveShell`` was |
|
59 | During developement and beta cycle, ``TerminalInteractiveShell`` was | |
60 | temporarly moved to ``IPtyhon.terminal.ptshell``. |
|
60 | temporarly moved to ``IPtyhon.terminal.ptshell``. | |
61 |
|
61 | |||
62 |
|
62 | |||
63 | Most of the above remarks also affect `IPython.core.debugger.Pdb`, the `%debug` |
|
63 | Most of the above remarks also affect `IPython.core.debugger.Pdb`, the `%debug` | |
64 | and `%pdb` magic which do not use readline anymore either. |
|
64 | and `%pdb` magic which do not use readline anymore either. | |
65 |
|
65 | |||
66 | The color handling has been slightly changed and is now exposed |
|
66 | The color handling has been slightly changed and is now exposed | |
67 | through, in particular the colors of prompts and as you type |
|
67 | through, in particular the colors of prompts and as you type | |
68 | highlighting can be affected by : |
|
68 | highlighting can be affected by : | |
69 | ``TerminalInteractiveShell.highlight_style``. With default |
|
69 | ``TerminalInteractiveShell.highlight_style``. With default | |
70 | configuration the ``--colors`` flag and ``%colors`` magic behavior |
|
70 | configuration the ``--colors`` flag and ``%colors`` magic behavior | |
71 | should be mostly unchanged. See the `colors <termcolour>`_ section of |
|
71 | should be mostly unchanged. See the `colors <termcolour>`_ section of | |
72 | our documentation |
|
72 | our documentation | |
73 |
|
73 | |||
74 | Provisional Changes |
|
74 | Provisional Changes | |
75 | ------------------- |
|
75 | ------------------- | |
76 |
|
76 | |||
77 | Provisional changes are in experimental functionality that may, or may not make |
|
77 | Provisional changes are in experimental functionality that may, or may not make | |
78 | it to future version of IPython, and which API may change without warnings. |
|
78 | it to future version of IPython, and which API may change without warnings. | |
79 | Activating these feature and using these API is at your own risk, and may have |
|
79 | Activating these feature and using these API is at your own risk, and may have | |
80 | security implication for your system, especially if used with the Jupyter notebook, |
|
80 | security implication for your system, especially if used with the Jupyter notebook, | |
81 |
|
81 | |||
82 | When running via the Jupyter notebook interfaces, or other compatible client, |
|
82 | When running via the Jupyter notebook interfaces, or other compatible client, | |
83 | you can enable rich documentation experimental functionality: |
|
83 | you can enable rich documentation experimental functionality: | |
84 |
|
84 | |||
85 | When the ``docrepr`` package is installed setting the boolean flag |
|
85 | When the ``docrepr`` package is installed setting the boolean flag | |
86 | ``InteractiveShell.sphinxify_docstring`` to ``True``, will process the various |
|
86 | ``InteractiveShell.sphinxify_docstring`` to ``True``, will process the various | |
87 | object through sphinx before displaying them (see the ``docrepr`` package |
|
87 | object through sphinx before displaying them (see the ``docrepr`` package | |
88 | documentation for more information. |
|
88 | documentation for more information. | |
89 |
|
89 | |||
90 | You need to also enable the IPython pager display rich HTML representation |
|
90 | You need to also enable the IPython pager display rich HTML representation | |
91 | using the ``InteractiveShell.enable_html_pager`` boolean configuration option. |
|
91 | using the ``InteractiveShell.enable_html_pager`` boolean configuration option. | |
92 | As usual you can set these configuration options globally in your configuration |
|
92 | As usual you can set these configuration options globally in your configuration | |
93 | files, alternatively you can turn them on dynamically using the following |
|
93 | files, alternatively you can turn them on dynamically using the following | |
94 | snippet: |
|
94 | snippet: | |
95 |
|
95 | |||
96 | .. code-block:: python |
|
96 | .. code-block:: python | |
97 |
|
97 | |||
98 | ip = get_ipython() |
|
98 | ip = get_ipython() | |
99 | ip.sphinxify_docstring = True |
|
99 | ip.sphinxify_docstring = True | |
100 | ip.enable_html_pager = True |
|
100 | ip.enable_html_pager = True | |
101 |
|
101 | |||
102 |
|
102 | |||
103 | You can test the effect of various combinations of the above configuration in |
|
103 | You can test the effect of various combinations of the above configuration in | |
104 | the Jupyter notebook, with things example like : |
|
104 | the Jupyter notebook, with things example like : | |
105 |
|
105 | |||
106 | .. code-block:: ipython |
|
106 | .. code-block:: ipython | |
107 |
|
107 | |||
108 | import numpy as np |
|
108 | import numpy as np | |
109 | np.histogram? |
|
109 | np.histogram? | |
110 |
|
110 | |||
111 |
|
111 | |||
112 | This is part of an effort to make Documentation in Python richer and provide in |
|
112 | This is part of an effort to make Documentation in Python richer and provide in | |
113 | the long term if possible dynamic examples that can contain math, images, |
|
113 | the long term if possible dynamic examples that can contain math, images, | |
114 | widgets... As stated above this is nightly experimental feature with a lot of |
|
114 | widgets... As stated above this is nightly experimental feature with a lot of | |
115 | (fun) problem to solve. We would be happy to get your feedback and expertise on |
|
115 | (fun) problem to solve. We would be happy to get your feedback and expertise on | |
116 | it. |
|
116 | it. | |
117 |
|
117 | |||
118 |
|
118 | |||
119 | Removed Feature |
|
119 | Removed Feature | |
120 | --------------- |
|
120 | --------------- | |
121 |
|
121 | |||
122 | - ``TerminalInteractiveShell.autoedit_syntax`` Has been broken for many years now |
|
122 | - ``TerminalInteractiveShell.autoedit_syntax`` Has been broken for many years now | |
123 | apparently. It has been removed. |
|
123 | apparently. It has been removed. | |
124 |
|
124 | |||
125 |
|
125 | |||
126 | Deprecated Features |
|
126 | Deprecated Features | |
127 | ------------------- |
|
127 | ------------------- | |
128 |
|
128 | |||
129 | Some deprecated feature, don't forget to enable ``DeprecationWarning`` as error |
|
129 | Some deprecated features are listed in this section. Don't forget to enable | |
130 | of you are using IPython in Continuous Integration setup or in your testing in general: |
|
130 | ``DeprecationWarning`` as an error if you are using IPython in a Continuous | |
|
131 | Integration setup or in your testing in general: | |||
131 |
|
132 | |||
132 | .. code-block:: python |
|
133 | .. code-block:: python | |
133 |
|
134 | |||
134 | import warnings |
|
135 | import warnings | |
135 | warnings.filterwarnings('error', '.*', DeprecationWarning, module='yourmodule.*') |
|
136 | warnings.filterwarnings('error', '.*', DeprecationWarning, module='yourmodule.*') | |
136 |
|
137 | |||
137 |
|
138 | |||
138 |
- ``hooks.fix_error_editor`` seem |
|
139 | - ``hooks.fix_error_editor`` seems unused and is pending deprecation. | |
139 | - `IPython/core/excolors.py:ExceptionColors` is deprecated. |
|
140 | - `IPython/core/excolors.py:ExceptionColors` is deprecated. | |
140 |
- `IPython.core.InteractiveShell:write()` is deprecated |
|
141 | - `IPython.core.InteractiveShell:write()` is deprecated; use `sys.stdout` instead. | |
141 |
- `IPython.core.InteractiveShell:write_err()` is deprecated |
|
142 | - `IPython.core.InteractiveShell:write_err()` is deprecated; use `sys.stderr` instead. | |
142 |
- The `formatter` keyword argument to `Inspector.info` in `IPython.core.oinspec` has no |
|
143 | - The `formatter` keyword argument to `Inspector.info` in `IPython.core.oinspec` has no effect. | |
143 |
- The `global_ns` keyword argument of IPython Embed was deprecated, and |
|
144 | - The `global_ns` keyword argument of IPython Embed was deprecated, and has no effect. Use `module` keyword argument instead. | |
144 |
|
145 | |||
145 |
|
146 | |||
146 | Known Issues: |
|
147 | Known Issues: | |
147 | ------------- |
|
148 | ------------- | |
148 |
|
149 | |||
149 | - ``<Esc>`` Key does not dismiss the completer and does not clear the current |
|
150 | - ``<Esc>`` Key does not dismiss the completer and does not clear the current | |
150 | buffer. This is an on purpose modification due to current technical |
|
151 | buffer. This is an on purpose modification due to current technical | |
151 | limitation. Cf :ghpull:`9572`. Escape the control character which is used |
|
152 | limitation. Cf :ghpull:`9572`. Escape the control character which is used | |
152 | for other shortcut, and there is no practical way to distinguish. Use Ctr-G |
|
153 | for other shortcut, and there is no practical way to distinguish. Use Ctr-G | |
153 | or Ctrl-C as an alternative. |
|
154 | or Ctrl-C as an alternative. | |
154 |
|
155 | |||
155 | - Cannot use ``Shift-Enter`` and ``Ctrl-Enter`` to submit code in terminal. cf |
|
156 | - Cannot use ``Shift-Enter`` and ``Ctrl-Enter`` to submit code in terminal. cf | |
156 | :ghissue:`9587` and :ghissue:`9401`. In terminal there is no practical way to |
|
157 | :ghissue:`9587` and :ghissue:`9401`. In terminal there is no practical way to | |
157 | distinguish these key sequences from a normal new line return. |
|
158 | distinguish these key sequences from a normal new line return. | |
158 |
|
159 | |||
159 | - ``PageUp`` and ``pageDown`` do not move through completion menu. |
|
160 | - ``PageUp`` and ``pageDown`` do not move through completion menu. | |
160 |
|
161 | |||
161 | - Color styles might not adapt to terminal emulator themes. This will need new |
|
162 | - Color styles might not adapt to terminal emulator themes. This will need new | |
162 | version of Pygments to be released, and can be mitigated with custom themes. |
|
163 | version of Pygments to be released, and can be mitigated with custom themes. | |
163 |
|
164 | |||
164 |
|
165 |
General Comments 0
You need to be logged in to leave comments.
Login now