##// END OF EJS Templates
Backport PR #12235: Fix compatibility with the latest release of Sphinx
Matthias Bussonnier -
Show More
@@ -1,122 +1,117 b''
1 # http://travis-ci.org/#!/ipython/ipython
1 # http://travis-ci.org/#!/ipython/ipython
2 language: python
2 language: python
3 os: linux
3 os: linux
4
4
5 addons:
5 addons:
6 apt:
6 apt:
7 packages:
7 packages:
8 - graphviz
8 - graphviz
9
9
10 python:
10 python:
11 - 3.6
11 - 3.6
12
12
13 sudo: false
13 sudo: false
14
14
15 env:
15 env:
16 global:
16 global:
17 - PATH=$TRAVIS_BUILD_DIR/pandoc:$PATH
17 - PATH=$TRAVIS_BUILD_DIR/pandoc:$PATH
18
18
19 group: edge
19 group: edge
20
20
21 before_install:
21 before_install:
22 - |
22 - |
23 # install Python on macOS
23 # install Python on macOS
24 if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
24 if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
25 env | sort
25 env | sort
26 if ! which python$TRAVIS_PYTHON_VERSION; then
26 if ! which python$TRAVIS_PYTHON_VERSION; then
27 HOMEBREW_NO_AUTO_UPDATE=1 brew tap minrk/homebrew-python-frameworks
27 HOMEBREW_NO_AUTO_UPDATE=1 brew tap minrk/homebrew-python-frameworks
28 HOMEBREW_NO_AUTO_UPDATE=1 brew cask install python-framework-${TRAVIS_PYTHON_VERSION/./}
28 HOMEBREW_NO_AUTO_UPDATE=1 brew cask install python-framework-${TRAVIS_PYTHON_VERSION/./}
29 fi
29 fi
30 python3 -m pip install virtualenv
30 python3 -m pip install virtualenv
31 python3 -m virtualenv -p $(which python$TRAVIS_PYTHON_VERSION) ~/travis-env
31 python3 -m virtualenv -p $(which python$TRAVIS_PYTHON_VERSION) ~/travis-env
32 source ~/travis-env/bin/activate
32 source ~/travis-env/bin/activate
33 fi
33 fi
34 - python --version
34 - python --version
35
35
36 install:
36 install:
37 - pip install pip --upgrade
37 - pip install pip --upgrade
38 - pip install setuptools --upgrade
38 - pip install setuptools --upgrade
39 - pip install -e file://$PWD#egg=ipython[test] --upgrade
39 - pip install -e file://$PWD#egg=ipython[test] --upgrade
40 - pip install trio curio --upgrade --upgrade-strategy eager
40 - pip install trio curio --upgrade --upgrade-strategy eager
41 - pip install pytest matplotlib
41 - pip install pytest matplotlib
42 - pip install codecov check-manifest --upgrade
42 - pip install codecov check-manifest --upgrade
43
43
44 script:
44 script:
45 - check-manifest
45 - check-manifest
46 - |
46 - |
47 if [[ "$TRAVIS_PYTHON_VERSION" == "nightly" ]]; then
47 if [[ "$TRAVIS_PYTHON_VERSION" == "nightly" ]]; then
48 # on nightly fake parso known the grammar
48 # on nightly fake parso known the grammar
49 cp /home/travis/virtualenv/python3.8-dev/lib/python3.8/site-packages/parso/python/grammar37.txt /home/travis/virtualenv/python3.8-dev/lib/python3.8/site-packages/parso/python/grammar38.txt
49 cp /home/travis/virtualenv/python3.8-dev/lib/python3.8/site-packages/parso/python/grammar37.txt /home/travis/virtualenv/python3.8-dev/lib/python3.8/site-packages/parso/python/grammar38.txt
50 fi
50 fi
51 - cd /tmp && iptest --coverage xml && cd -
51 - cd /tmp && iptest --coverage xml && cd -
52 - pytest IPython
52 - pytest IPython
53 # On the latest Python (on Linux) only, make sure that the docs build.
53 # On the latest Python (on Linux) only, make sure that the docs build.
54 - |
54 - |
55 if [[ "$TRAVIS_PYTHON_VERSION" == "3.7" ]] && [[ "$TRAVIS_OS_NAME" == "linux" ]]; then
55 if [[ "$TRAVIS_PYTHON_VERSION" == "3.7" ]] && [[ "$TRAVIS_OS_NAME" == "linux" ]]; then
56 pip install -r docs/requirements.txt
56 pip install -r docs/requirements.txt
57 python tools/fixup_whats_new_pr.py
57 python tools/fixup_whats_new_pr.py
58 make -C docs/ html SPHINXOPTS="-W"
58 make -C docs/ html SPHINXOPTS="-W"
59 fi
59 fi
60
60
61 after_success:
61 after_success:
62 - cp /tmp/ipy_coverage.xml ./
62 - cp /tmp/ipy_coverage.xml ./
63 - cp /tmp/.coverage ./
63 - cp /tmp/.coverage ./
64 - codecov
64 - codecov
65
65
66 matrix:
66 matrix:
67 include:
67 include:
68 - arch: amd64
68 - arch: amd64
69 python: "3.7"
69 python: "3.7"
70 dist: xenial
70 dist: xenial
71 sudo: true
71 sudo: true
72 - arch: arm64
73 python: "3.7"
74 dist: xenial
75 env: ARM64=True IPYTHON_TESTING_TIMEOUT_SCALE=2
76 sudo: true
77 - arch: amd64
72 - arch: amd64
78 python: "3.8-dev"
73 python: "3.8-dev"
79 dist: xenial
74 dist: xenial
80 sudo: true
75 sudo: true
81 - arch: amd64
76 - arch: amd64
82 python: "3.7-dev"
77 python: "3.7-dev"
83 dist: xenial
78 dist: xenial
84 sudo: true
79 sudo: true
85 - arch: amd64
80 - arch: amd64
86 python: "nightly"
81 python: "nightly"
87 dist: xenial
82 dist: xenial
88 sudo: true
83 sudo: true
89 - arch: arm64
84 - arch: arm64
90 python: "nightly"
85 python: "nightly"
91 dist: bionic
86 dist: bionic
92 env: ARM64=True
87 env: ARM64=True
93 sudo: true
88 sudo: true
94 - os: osx
89 - os: osx
95 language: generic
90 language: generic
96 python: 3.6
91 python: 3.6
97 env: TRAVIS_PYTHON_VERSION=3.6
92 env: TRAVIS_PYTHON_VERSION=3.6
98 - os: osx
93 - os: osx
99 language: generic
94 language: generic
100 python: 3.7
95 python: 3.7
101 env: TRAVIS_PYTHON_VERSION=3.7
96 env: TRAVIS_PYTHON_VERSION=3.7
102 allow_failures:
97 allow_failures:
103 - python: nightly
98 - python: nightly
104
99
105 before_deploy:
100 before_deploy:
106 - rm -rf dist/
101 - rm -rf dist/
107 - python setup.py sdist
102 - python setup.py sdist
108 - python setup.py bdist_wheel
103 - python setup.py bdist_wheel
109
104
110 deploy:
105 deploy:
111 provider: releases
106 provider: releases
112 api_key:
107 api_key:
113 secure: Y/Ae9tYs5aoBU8bDjN2YrwGG6tCbezj/h3Lcmtx8HQavSbBgXnhnZVRb2snOKD7auqnqjfT/7QMm4ZyKvaOEgyggGktKqEKYHC8KOZ7yp8I5/UMDtk6j9TnXpSqqBxPiud4MDV76SfRYEQiaDoG4tGGvSfPJ9KcNjKrNvSyyxns=
108 secure: Y/Ae9tYs5aoBU8bDjN2YrwGG6tCbezj/h3Lcmtx8HQavSbBgXnhnZVRb2snOKD7auqnqjfT/7QMm4ZyKvaOEgyggGktKqEKYHC8KOZ7yp8I5/UMDtk6j9TnXpSqqBxPiud4MDV76SfRYEQiaDoG4tGGvSfPJ9KcNjKrNvSyyxns=
114 file: dist/*
109 file: dist/*
115 file_glob: true
110 file_glob: true
116 skip_cleanup: true
111 skip_cleanup: true
117 on:
112 on:
118 repo: ipython/ipython
113 repo: ipython/ipython
119 all_branches: true # Backports are released from e.g. 5.x branch
114 all_branches: true # Backports are released from e.g. 5.x branch
120 tags: true
115 tags: true
121 python: 3.6 # Any version should work, but we only need one
116 python: 3.6 # Any version should work, but we only need one
122 condition: $TRAVIS_OS_NAME = "linux"
117 condition: $TRAVIS_OS_NAME = "linux"
@@ -1,295 +1,318 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 # http://read-the-docs.readthedocs.io/en/latest/faq.html
20 # http://read-the-docs.readthedocs.io/en/latest/faq.html
21 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
21 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
22
22
23 if ON_RTD:
23 if ON_RTD:
24 tags.add('rtd')
24 tags.add('rtd')
25
25
26 # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
26 # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
27 for name in ('config', 'api', 'magics', 'shortcuts'):
27 for name in ('config', 'api', 'magics', 'shortcuts'):
28 fname = 'autogen_{}.py'.format(name)
28 fname = 'autogen_{}.py'.format(name)
29 fpath = os.path.abspath(os.path.join('..', fname))
29 fpath = os.path.abspath(os.path.join('..', fname))
30 with open(fpath) as f:
30 with open(fpath) as f:
31 exec(compile(f.read(), fname, 'exec'), {
31 exec(compile(f.read(), fname, 'exec'), {
32 '__file__': fpath,
32 '__file__': fpath,
33 '__name__': '__main__',
33 '__name__': '__main__',
34 })
34 })
35 else:
35 else:
36 import sphinx_rtd_theme
36 import sphinx_rtd_theme
37 html_theme = "sphinx_rtd_theme"
37 html_theme = "sphinx_rtd_theme"
38 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
38 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
39
39
40 # If your extensions are in another directory, add it here. If the directory
40 # If your extensions are in another directory, add it here. If the directory
41 # is relative to the documentation root, use os.path.abspath to make it
41 # is relative to the documentation root, use os.path.abspath to make it
42 # absolute, like shown here.
42 # absolute, like shown here.
43 sys.path.insert(0, os.path.abspath('../sphinxext'))
43 sys.path.insert(0, os.path.abspath('../sphinxext'))
44
44
45 # We load the ipython release info into a dict by explicit execution
45 # We load the ipython release info into a dict by explicit execution
46 iprelease = {}
46 iprelease = {}
47 exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease)
47 exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease)
48
48
49 # General configuration
49 # General configuration
50 # ---------------------
50 # ---------------------
51
51
52 # Add any Sphinx extension module names here, as strings. They can be extensions
52 # Add any Sphinx extension module names here, as strings. They can be extensions
53 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
53 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
54 extensions = [
54 extensions = [
55 'sphinx.ext.autodoc',
55 'sphinx.ext.autodoc',
56 'sphinx.ext.autosummary',
56 'sphinx.ext.autosummary',
57 'sphinx.ext.doctest',
57 'sphinx.ext.doctest',
58 'sphinx.ext.inheritance_diagram',
58 'sphinx.ext.inheritance_diagram',
59 'sphinx.ext.intersphinx',
59 'sphinx.ext.intersphinx',
60 'sphinx.ext.graphviz',
60 'sphinx.ext.graphviz',
61 'IPython.sphinxext.ipython_console_highlighting',
61 'IPython.sphinxext.ipython_console_highlighting',
62 'IPython.sphinxext.ipython_directive',
62 'IPython.sphinxext.ipython_directive',
63 'sphinx.ext.napoleon', # to preprocess docstrings
63 'sphinx.ext.napoleon', # to preprocess docstrings
64 'github', # for easy GitHub links
64 'github', # for easy GitHub links
65 'magics',
65 'magics',
66 'configtraits',
66 'configtraits',
67 ]
67 ]
68
68
69 # Add any paths that contain templates here, relative to this directory.
69 # Add any paths that contain templates here, relative to this directory.
70 templates_path = ['_templates']
70 templates_path = ['_templates']
71
71
72 # The suffix of source filenames.
72 # The suffix of source filenames.
73 source_suffix = '.rst'
73 source_suffix = '.rst'
74
74
75 rst_prolog = ''
75 rst_prolog = ''
76
76
77 def is_stable(extra):
77 def is_stable(extra):
78 for ext in {'dev', 'b', 'rc'}:
78 for ext in {'dev', 'b', 'rc'}:
79 if ext in extra:
79 if ext in extra:
80 return False
80 return False
81 return True
81 return True
82
82
83 if is_stable(iprelease['_version_extra']):
83 if is_stable(iprelease['_version_extra']):
84 tags.add('ipystable')
84 tags.add('ipystable')
85 print('Adding Tag: ipystable')
85 print('Adding Tag: ipystable')
86 else:
86 else:
87 tags.add('ipydev')
87 tags.add('ipydev')
88 print('Adding Tag: ipydev')
88 print('Adding Tag: ipydev')
89 rst_prolog += """
89 rst_prolog += """
90 .. warning::
90 .. warning::
91
91
92 This documentation covers a development version of IPython. The development
92 This documentation covers a development version of IPython. The development
93 version may differ significantly from the latest stable release.
93 version may differ significantly from the latest stable release.
94 """
94 """
95
95
96 rst_prolog += """
96 rst_prolog += """
97 .. important::
97 .. important::
98
98
99 This documentation covers IPython versions 6.0 and higher. Beginning with
99 This documentation covers IPython versions 6.0 and higher. Beginning with
100 version 6.0, IPython stopped supporting compatibility with Python versions
100 version 6.0, IPython stopped supporting compatibility with Python versions
101 lower than 3.3 including all versions of Python 2.7.
101 lower than 3.3 including all versions of Python 2.7.
102
102
103 If you are looking for an IPython version compatible with Python 2.7,
103 If you are looking for an IPython version compatible with Python 2.7,
104 please use the IPython 5.x LTS release and refer to its documentation (LTS
104 please use the IPython 5.x LTS release and refer to its documentation (LTS
105 is the long term support release).
105 is the long term support release).
106
106
107 """
107 """
108
108
109 # The master toctree document.
109 # The master toctree document.
110 master_doc = 'index'
110 master_doc = 'index'
111
111
112 # General substitutions.
112 # General substitutions.
113 project = 'IPython'
113 project = 'IPython'
114 copyright = 'The IPython Development Team'
114 copyright = 'The IPython Development Team'
115
115
116 # ghissue config
116 # ghissue config
117 github_project_url = "https://github.com/ipython/ipython"
117 github_project_url = "https://github.com/ipython/ipython"
118
118
119 # numpydoc config
119 # numpydoc config
120 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
120 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
121 numpydoc_class_members_toctree = False
121 numpydoc_class_members_toctree = False
122 warning_is_error = True
122 warning_is_error = True
123
123
124 import logging
125
126 class ConfigtraitFilter(logging.Filter):
127 """
128 This is a filter to remove in sphinx 3+ the error about config traits being duplicated.
129
130 As we autogenerate configuration traits from, subclasses have lots of
131 duplication and we want to silence them. Indeed we build on travis with
132 warnings-as-error set to True, so those duplicate items make the build fail.
133 """
134
135 def filter(self, record):
136 if record.args and record.args[0] == 'configtrait' and 'duplicate' in record.msg:
137 return False
138 return True
139
140 ct_filter = ConfigtraitFilter()
141
142 import sphinx.util
143 logger = sphinx.util.logging.getLogger('sphinx.domains.std').logger
144
145 logger.addFilter(ct_filter)
146
124 # The default replacements for |version| and |release|, also used in various
147 # The default replacements for |version| and |release|, also used in various
125 # other places throughout the built documents.
148 # other places throughout the built documents.
126 #
149 #
127 # The full version, including alpha/beta/rc tags.
150 # The full version, including alpha/beta/rc tags.
128 release = "%s" % iprelease['version']
151 release = "%s" % iprelease['version']
129 # Just the X.Y.Z part, no '-dev'
152 # Just the X.Y.Z part, no '-dev'
130 version = iprelease['version'].split('-', 1)[0]
153 version = iprelease['version'].split('-', 1)[0]
131
154
132
155
133 # There are two options for replacing |today|: either, you set today to some
156 # There are two options for replacing |today|: either, you set today to some
134 # non-false value, then it is used:
157 # non-false value, then it is used:
135 #today = ''
158 #today = ''
136 # Else, today_fmt is used as the format for a strftime call.
159 # Else, today_fmt is used as the format for a strftime call.
137 today_fmt = '%B %d, %Y'
160 today_fmt = '%B %d, %Y'
138
161
139 # List of documents that shouldn't be included in the build.
162 # List of documents that shouldn't be included in the build.
140 #unused_docs = []
163 #unused_docs = []
141
164
142 # Exclude these glob-style patterns when looking for source files. They are
165 # Exclude these glob-style patterns when looking for source files. They are
143 # relative to the source/ directory.
166 # relative to the source/ directory.
144 exclude_patterns = []
167 exclude_patterns = []
145
168
146
169
147 # If true, '()' will be appended to :func: etc. cross-reference text.
170 # If true, '()' will be appended to :func: etc. cross-reference text.
148 #add_function_parentheses = True
171 #add_function_parentheses = True
149
172
150 # If true, the current module name will be prepended to all description
173 # If true, the current module name will be prepended to all description
151 # unit titles (such as .. function::).
174 # unit titles (such as .. function::).
152 #add_module_names = True
175 #add_module_names = True
153
176
154 # If true, sectionauthor and moduleauthor directives will be shown in the
177 # If true, sectionauthor and moduleauthor directives will be shown in the
155 # output. They are ignored by default.
178 # output. They are ignored by default.
156 #show_authors = False
179 #show_authors = False
157
180
158 # The name of the Pygments (syntax highlighting) style to use.
181 # The name of the Pygments (syntax highlighting) style to use.
159 pygments_style = 'sphinx'
182 pygments_style = 'sphinx'
160
183
161 # Set the default role so we can use `foo` instead of ``foo``
184 # Set the default role so we can use `foo` instead of ``foo``
162 default_role = 'literal'
185 default_role = 'literal'
163
186
164 # Options for HTML output
187 # Options for HTML output
165 # -----------------------
188 # -----------------------
166
189
167 # The style sheet to use for HTML and HTML Help pages. A file of that name
190 # The style sheet to use for HTML and HTML Help pages. A file of that name
168 # must exist either in Sphinx' static/ path, or in one of the custom paths
191 # must exist either in Sphinx' static/ path, or in one of the custom paths
169 # given in html_static_path.
192 # given in html_static_path.
170 # html_style = 'default.css'
193 # html_style = 'default.css'
171
194
172
195
173 # The name for this set of Sphinx documents. If None, it defaults to
196 # The name for this set of Sphinx documents. If None, it defaults to
174 # "<project> v<release> documentation".
197 # "<project> v<release> documentation".
175 #html_title = None
198 #html_title = None
176
199
177 # The name of an image file (within the static path) to place at the top of
200 # The name of an image file (within the static path) to place at the top of
178 # the sidebar.
201 # the sidebar.
179 #html_logo = None
202 #html_logo = None
180
203
181 # Add any paths that contain custom static files (such as style sheets) here,
204 # Add any paths that contain custom static files (such as style sheets) here,
182 # relative to this directory. They are copied after the builtin static files,
205 # relative to this directory. They are copied after the builtin static files,
183 # so a file named "default.css" will overwrite the builtin "default.css".
206 # so a file named "default.css" will overwrite the builtin "default.css".
184 html_static_path = ['_static']
207 html_static_path = ['_static']
185
208
186 # Favicon needs the directory name
209 # Favicon needs the directory name
187 html_favicon = '_static/favicon.ico'
210 html_favicon = '_static/favicon.ico'
188 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
211 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
189 # using the given strftime format.
212 # using the given strftime format.
190 html_last_updated_fmt = '%b %d, %Y'
213 html_last_updated_fmt = '%b %d, %Y'
191
214
192 # If true, SmartyPants will be used to convert quotes and dashes to
215 # If true, SmartyPants will be used to convert quotes and dashes to
193 # typographically correct entities.
216 # typographically correct entities.
194 #html_use_smartypants = True
217 #html_use_smartypants = True
195
218
196 # Custom sidebar templates, maps document names to template names.
219 # Custom sidebar templates, maps document names to template names.
197 #html_sidebars = {}
220 #html_sidebars = {}
198
221
199 # Additional templates that should be rendered to pages, maps page names to
222 # Additional templates that should be rendered to pages, maps page names to
200 # template names.
223 # template names.
201 html_additional_pages = {
224 html_additional_pages = {
202 'interactive/htmlnotebook': 'notebook_redirect.html',
225 'interactive/htmlnotebook': 'notebook_redirect.html',
203 'interactive/notebook': 'notebook_redirect.html',
226 'interactive/notebook': 'notebook_redirect.html',
204 'interactive/nbconvert': 'notebook_redirect.html',
227 'interactive/nbconvert': 'notebook_redirect.html',
205 'interactive/public_server': 'notebook_redirect.html',
228 'interactive/public_server': 'notebook_redirect.html',
206 }
229 }
207
230
208 # If false, no module index is generated.
231 # If false, no module index is generated.
209 #html_use_modindex = True
232 #html_use_modindex = True
210
233
211 # If true, the reST sources are included in the HTML build as _sources/<name>.
234 # If true, the reST sources are included in the HTML build as _sources/<name>.
212 #html_copy_source = True
235 #html_copy_source = True
213
236
214 # If true, an OpenSearch description file will be output, and all pages will
237 # If true, an OpenSearch description file will be output, and all pages will
215 # contain a <link> tag referring to it. The value of this option must be the
238 # contain a <link> tag referring to it. The value of this option must be the
216 # base URL from which the finished HTML is served.
239 # base URL from which the finished HTML is served.
217 #html_use_opensearch = ''
240 #html_use_opensearch = ''
218
241
219 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
242 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
220 #html_file_suffix = ''
243 #html_file_suffix = ''
221
244
222 # Output file base name for HTML help builder.
245 # Output file base name for HTML help builder.
223 htmlhelp_basename = 'ipythondoc'
246 htmlhelp_basename = 'ipythondoc'
224
247
225 intersphinx_mapping = {'python': ('https://docs.python.org/3/', None),
248 intersphinx_mapping = {'python': ('https://docs.python.org/3/', None),
226 'rpy2': ('https://rpy2.github.io/doc/latest/html/', None),
249 'rpy2': ('https://rpy2.github.io/doc/latest/html/', None),
227 'jupyterclient': ('https://jupyter-client.readthedocs.io/en/latest/', None),
250 'jupyterclient': ('https://jupyter-client.readthedocs.io/en/latest/', None),
228 'jupyter': ('https://jupyter.readthedocs.io/en/latest/', None),
251 'jupyter': ('https://jupyter.readthedocs.io/en/latest/', None),
229 'jedi': ('https://jedi.readthedocs.io/en/latest/', None),
252 'jedi': ('https://jedi.readthedocs.io/en/latest/', None),
230 'traitlets': ('https://traitlets.readthedocs.io/en/latest/', None),
253 'traitlets': ('https://traitlets.readthedocs.io/en/latest/', None),
231 'ipykernel': ('https://ipykernel.readthedocs.io/en/latest/', None),
254 'ipykernel': ('https://ipykernel.readthedocs.io/en/latest/', None),
232 'prompt_toolkit' : ('https://python-prompt-toolkit.readthedocs.io/en/stable/', None),
255 'prompt_toolkit' : ('https://python-prompt-toolkit.readthedocs.io/en/stable/', None),
233 'ipywidgets': ('https://ipywidgets.readthedocs.io/en/stable/', None),
256 'ipywidgets': ('https://ipywidgets.readthedocs.io/en/stable/', None),
234 'ipyparallel': ('https://ipyparallel.readthedocs.io/en/stable/', None),
257 'ipyparallel': ('https://ipyparallel.readthedocs.io/en/stable/', None),
235 'pip': ('https://pip.pypa.io/en/stable/', None)
258 'pip': ('https://pip.pypa.io/en/stable/', None)
236 }
259 }
237
260
238 # Options for LaTeX output
261 # Options for LaTeX output
239 # ------------------------
262 # ------------------------
240
263
241 # The paper size ('letter' or 'a4').
264 # The paper size ('letter' or 'a4').
242 latex_paper_size = 'letter'
265 latex_paper_size = 'letter'
243
266
244 # The font size ('10pt', '11pt' or '12pt').
267 # The font size ('10pt', '11pt' or '12pt').
245 latex_font_size = '11pt'
268 latex_font_size = '11pt'
246
269
247 # Grouping the document tree into LaTeX files. List of tuples
270 # Grouping the document tree into LaTeX files. List of tuples
248 # (source start file, target name, title, author, document class [howto/manual]).
271 # (source start file, target name, title, author, document class [howto/manual]).
249
272
250 latex_documents = [
273 latex_documents = [
251 ('index', 'ipython.tex', 'IPython Documentation',
274 ('index', 'ipython.tex', 'IPython Documentation',
252 u"""The IPython Development Team""", 'manual', True),
275 u"""The IPython Development Team""", 'manual', True),
253 ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
276 ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
254 'Using IPython on Windows HPC Server 2008',
277 'Using IPython on Windows HPC Server 2008',
255 u"Brian E. Granger", 'manual', True)
278 u"Brian E. Granger", 'manual', True)
256 ]
279 ]
257
280
258 # The name of an image file (relative to this directory) to place at the top of
281 # The name of an image file (relative to this directory) to place at the top of
259 # the title page.
282 # the title page.
260 #latex_logo = None
283 #latex_logo = None
261
284
262 # For "manual" documents, if this is true, then toplevel headings are parts,
285 # For "manual" documents, if this is true, then toplevel headings are parts,
263 # not chapters.
286 # not chapters.
264 #latex_use_parts = False
287 #latex_use_parts = False
265
288
266 # Additional stuff for the LaTeX preamble.
289 # Additional stuff for the LaTeX preamble.
267 #latex_preamble = ''
290 #latex_preamble = ''
268
291
269 # Documents to append as an appendix to all manuals.
292 # Documents to append as an appendix to all manuals.
270 #latex_appendices = []
293 #latex_appendices = []
271
294
272 # If false, no module index is generated.
295 # If false, no module index is generated.
273 latex_use_modindex = True
296 latex_use_modindex = True
274
297
275
298
276 # Options for texinfo output
299 # Options for texinfo output
277 # --------------------------
300 # --------------------------
278
301
279 texinfo_documents = [
302 texinfo_documents = [
280 (master_doc, 'ipython', 'IPython Documentation',
303 (master_doc, 'ipython', 'IPython Documentation',
281 'The IPython Development Team',
304 'The IPython Development Team',
282 'IPython',
305 'IPython',
283 'IPython Documentation',
306 'IPython Documentation',
284 'Programming',
307 'Programming',
285 1),
308 1),
286 ]
309 ]
287
310
288 modindex_common_prefix = ['IPython.']
311 modindex_common_prefix = ['IPython.']
289
312
290
313
291 # Cleanup
314 # Cleanup
292 # -------
315 # -------
293 # delete release info to avoid pickling errors from sphinx
316 # delete release info to avoid pickling errors from sphinx
294
317
295 del iprelease
318 del iprelease
@@ -1,175 +1,175 b''
1 Making simple Python wrapper kernels
1 Making simple Python wrapper kernels
2 ====================================
2 ====================================
3
3
4 .. versionadded:: 3.0
4 .. versionadded:: 3.0
5
5
6 You can now re-use the kernel machinery in IPython to easily make new kernels.
6 You can now re-use the kernel machinery in IPython to easily make new kernels.
7 This is useful for languages that have Python bindings, such as `Octave
7 This is useful for languages that have Python bindings, such as `Octave
8 <http://www.gnu.org/software/octave/>`_ (via
8 <http://www.gnu.org/software/octave/>`_ (via
9 `Oct2Py <http://blink1073.github.io/oct2py/>`_), or languages
9 `Oct2Py <http://blink1073.github.io/oct2py/>`_), or languages
10 where the REPL can be controlled in a tty using `pexpect <http://pexpect.readthedocs.io/en/latest/>`_,
10 where the REPL can be controlled in a tty using `pexpect <http://pexpect.readthedocs.io/en/latest/>`_,
11 such as bash.
11 such as bash.
12
12
13 .. seealso::
13 .. seealso::
14
14
15 `bash_kernel <https://github.com/takluyver/bash_kernel>`_
15 `bash_kernel <https://github.com/takluyver/bash_kernel>`_
16 A simple kernel for bash, written using this machinery
16 A simple kernel for bash, written using this machinery
17
17
18 Required steps
18 Required steps
19 --------------
19 --------------
20
20
21 Subclass :class:`ipykernel.kernelbase.Kernel`, and implement the
21 Subclass :class:`ipykernel.kernelbase.Kernel`, and implement the
22 following methods and attributes:
22 following methods and attributes:
23
23
24 .. class:: MyKernel
24 .. class:: MyKernel
25
25
26 .. attribute:: implementation
26 .. attribute:: implementation
27 implementation_version
27 implementation_version
28 language
28 language
29 language_version
29 language_version
30 banner
30 banner
31
31
32 Information for :ref:`msging_kernel_info` replies. 'Implementation' refers
32 Information for :ref:`msging_kernel_info` replies. 'Implementation' refers
33 to the kernel (e.g. IPython), and 'language' refers to the language it
33 to the kernel (e.g. IPython), and 'language' refers to the language it
34 interprets (e.g. Python). The 'banner' is displayed to the user in console
34 interprets (e.g. Python). The 'banner' is displayed to the user in console
35 UIs before the first prompt. All of these values are strings.
35 UIs before the first prompt. All of these values are strings.
36
36
37 .. attribute:: language_info
37 .. attribute:: language_info
38
38
39 Language information for :ref:`msging_kernel_info` replies, in a dictionary.
39 Language information for :ref:`msging_kernel_info` replies, in a dictionary.
40 This should contain the key ``mimetype`` with the mimetype of code in the
40 This should contain the key ``mimetype`` with the mimetype of code in the
41 target language (e.g. ``'text/x-python'``), and ``file_extension`` (e.g.
41 target language (e.g. ``'text/x-python'``), and ``file_extension`` (e.g.
42 ``'py'``).
42 ``'py'``).
43 It may also contain keys ``codemirror_mode`` and ``pygments_lexer`` if they
43 It may also contain keys ``codemirror_mode`` and ``pygments_lexer`` if they
44 need to differ from :attr:`language`.
44 need to differ from :attr:`language`.
45
45
46 Other keys may be added to this later.
46 Other keys may be added to this later.
47
47
48 .. method:: do_execute(code, silent, store_history=True, user_expressions=None, allow_stdin=False)
48 .. method:: do_execute(code, silent, store_history=True, user_expressions=None, allow_stdin=False)
49
49
50 Execute user code.
50 Execute user code.
51
51
52 :param str code: The code to be executed.
52 :param str code: The code to be executed.
53 :param bool silent: Whether to display output.
53 :param bool silent: Whether to display output.
54 :param bool store_history: Whether to record this code in history and
54 :param bool store_history: Whether to record this code in history and
55 increase the execution count. If silent is True, this is implicitly
55 increase the execution count. If silent is True, this is implicitly
56 False.
56 False.
57 :param dict user_expressions: Mapping of names to expressions to evaluate
57 :param dict user_expressions: Mapping of names to expressions to evaluate
58 after the code has run. You can ignore this if you need to.
58 after the code has run. You can ignore this if you need to.
59 :param bool allow_stdin: Whether the frontend can provide input on request
59 :param bool allow_stdin: Whether the frontend can provide input on request
60 (e.g. for Python's :func:`raw_input`).
60 (e.g. for Python's :func:`raw_input`).
61
61
62 Your method should return a dict containing the fields described in
62 Your method should return a dict containing the fields described in
63 :ref:`execution_results`. To display output, it can send messages
63 :ref:`execution_results`. To display output, it can send messages
64 using :meth:`~ipykernel.kernelbase.Kernel.send_response`.
64 using :meth:`~ipykernel.kernelbase.Kernel.send_response`.
65 See :doc:`messaging` for details of the different message types.
65 See :doc:`messaging` for details of the different message types.
66
66
67 To launch your kernel, add this at the end of your module::
67 To launch your kernel, add this at the end of your module::
68
68
69 if __name__ == '__main__':
69 if __name__ == '__main__':
70 from ipykernel.kernelapp import IPKernelApp
70 from ipykernel.kernelapp import IPKernelApp
71 IPKernelApp.launch_instance(kernel_class=MyKernel)
71 IPKernelApp.launch_instance(kernel_class=MyKernel)
72
72
73 Example
73 Example
74 -------
74 -------
75
75
76 ``echokernel.py`` will simply echo any input it's given to stdout::
76 ``echokernel.py`` will simply echo any input it's given to stdout::
77
77
78 from ipykernel.kernelbase import Kernel
78 from ipykernel.kernelbase import Kernel
79
79
80 class EchoKernel(Kernel):
80 class EchoKernel(Kernel):
81 implementation = 'Echo'
81 implementation = 'Echo'
82 implementation_version = '1.0'
82 implementation_version = '1.0'
83 language = 'no-op'
83 language = 'no-op'
84 language_version = '0.1'
84 language_version = '0.1'
85 language_info = {'mimetype': 'text/plain'}
85 language_info = {'mimetype': 'text/plain'}
86 banner = "Echo kernel - as useful as a parrot"
86 banner = "Echo kernel - as useful as a parrot"
87
87
88 def do_execute(self, code, silent, store_history=True, user_expressions=None,
88 def do_execute(self, code, silent, store_history=True, user_expressions=None,
89 allow_stdin=False):
89 allow_stdin=False):
90 if not silent:
90 if not silent:
91 stream_content = {'name': 'stdout', 'text': code}
91 stream_content = {'name': 'stdout', 'text': code}
92 self.send_response(self.iopub_socket, 'stream', stream_content)
92 self.send_response(self.iopub_socket, 'stream', stream_content)
93
93
94 return {'status': 'ok',
94 return {'status': 'ok',
95 # The base class increments the execution count
95 # The base class increments the execution count
96 'execution_count': self.execution_count,
96 'execution_count': self.execution_count,
97 'payload': [],
97 'payload': [],
98 'user_expressions': {},
98 'user_expressions': {},
99 }
99 }
100
100
101 if __name__ == '__main__':
101 if __name__ == '__main__':
102 from ipykernel.kernelapp import IPKernelApp
102 from ipykernel.kernelapp import IPKernelApp
103 IPKernelApp.launch_instance(kernel_class=EchoKernel)
103 IPKernelApp.launch_instance(kernel_class=EchoKernel)
104
104
105 Here's the Kernel spec ``kernel.json`` file for this::
105 Here's the Kernel spec ``kernel.json`` file for this::
106
106
107 {"argv":["python","-m","echokernel", "-f", "{connection_file}"],
107 {"argv":["python","-m","echokernel", "-f", "{connection_file}"],
108 "display_name":"Echo"
108 "display_name":"Echo"
109 }
109 }
110
110
111
111
112 Optional steps
112 Optional steps
113 --------------
113 --------------
114
114
115 You can override a number of other methods to improve the functionality of your
115 You can override a number of other methods to improve the functionality of your
116 kernel. All of these methods should return a dictionary as described in the
116 kernel. All of these methods should return a dictionary as described in the
117 relevant section of the :doc:`messaging spec <messaging>`.
117 relevant section of the :doc:`messaging spec <messaging>`.
118
118
119 .. class:: MyKernel
119 .. class:: MyBetterKernel
120
120
121 .. method:: do_complete(code, cusor_pos)
121 .. method:: do_complete(code, cusor_pos)
122
122
123 Code completion
123 Code completion
124
124
125 :param str code: The code already present
125 :param str code: The code already present
126 :param int cursor_pos: The position in the code where completion is requested
126 :param int cursor_pos: The position in the code where completion is requested
127
127
128 .. seealso::
128 .. seealso::
129
129
130 :ref:`msging_completion` messages
130 :ref:`msging_completion` messages
131
131
132 .. method:: do_inspect(code, cusor_pos, detail_level=0)
132 .. method:: do_inspect(code, cusor_pos, detail_level=0)
133
133
134 Object introspection
134 Object introspection
135
135
136 :param str code: The code
136 :param str code: The code
137 :param int cursor_pos: The position in the code where introspection is requested
137 :param int cursor_pos: The position in the code where introspection is requested
138 :param int detail_level: 0 or 1 for more or less detail. In IPython, 1 gets
138 :param int detail_level: 0 or 1 for more or less detail. In IPython, 1 gets
139 the source code.
139 the source code.
140
140
141 .. seealso::
141 .. seealso::
142
142
143 :ref:`msging_inspection` messages
143 :ref:`msging_inspection` messages
144
144
145 .. method:: do_history(hist_access_type, output, raw, session=None, start=None, stop=None, n=None, pattern=None, unique=False)
145 .. method:: do_history(hist_access_type, output, raw, session=None, start=None, stop=None, n=None, pattern=None, unique=False)
146
146
147 History access. Only the relevant parameters for the type of history
147 History access. Only the relevant parameters for the type of history
148 request concerned will be passed, so your method definition must have defaults
148 request concerned will be passed, so your method definition must have defaults
149 for all the arguments shown with defaults here.
149 for all the arguments shown with defaults here.
150
150
151 .. seealso::
151 .. seealso::
152
152
153 :ref:`msging_history` messages
153 :ref:`msging_history` messages
154
154
155 .. method:: do_is_complete(code)
155 .. method:: do_is_complete(code)
156
156
157 Is code entered in a console-like interface complete and ready to execute,
157 Is code entered in a console-like interface complete and ready to execute,
158 or should a continuation prompt be shown?
158 or should a continuation prompt be shown?
159
159
160 :param str code: The code entered so far - possibly multiple lines
160 :param str code: The code entered so far - possibly multiple lines
161
161
162 .. seealso::
162 .. seealso::
163
163
164 :ref:`msging_is_complete` messages
164 :ref:`msging_is_complete` messages
165
165
166 .. method:: do_shutdown(restart)
166 .. method:: do_shutdown(restart)
167
167
168 Shutdown the kernel. You only need to handle your own clean up - the kernel
168 Shutdown the kernel. You only need to handle your own clean up - the kernel
169 machinery will take care of cleaning up its own things before stopping.
169 machinery will take care of cleaning up its own things before stopping.
170
170
171 :param bool restart: Whether the kernel will be started again afterwards
171 :param bool restart: Whether the kernel will be started again afterwards
172
172
173 .. seealso::
173 .. seealso::
174
174
175 :ref:`msging_shutdown` messages
175 :ref:`msging_shutdown` messages
@@ -1,17 +1,16 b''
1 """Directives and roles for documenting traitlets config options.
1 """Directives and roles for documenting traitlets config options.
2
2
3 ::
3 ::
4
4
5 .. configtrait:: Application.log_datefmt
5 .. configtrait:: Application.log_datefmt
6
6
7 Description goes here.
7 Description goes here.
8
8
9 Cross reference like this: :configtrait:`Application.log_datefmt`.
9 Cross reference like this: :configtrait:`Application.log_datefmt`.
10 """
10 """
11 from sphinx.locale import l_
11
12 from sphinx.util.docfields import Field
13
12
14 def setup(app):
13 def setup(app):
15 app.add_object_type('configtrait', 'configtrait', objname='Config option')
14 app.add_object_type('configtrait', 'configtrait', objname='Config option')
16 metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
15 metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
17 return metadata
16 return metadata
General Comments 0
You need to be logged in to leave comments. Login now