8000 [MRG + 2] [MAINT] Update to Sphinx-Gallery 0.1.7 (#7986) · scikit-learn/scikit-learn@bddda7b · GitHub
[go: up one dir, main page]
Skip to content

Commit bddda7b

Browse files
Titan-Clesteve
Titan-C
authored and
lesteve
committed
[MRG + 2] [MAINT] Update to Sphinx-Gallery 0.1.7 (#7986)
and use latest version of sphinx in CircleCI
1 parent aea6462 commit bddda7b

File tree

11 files changed

+367
-195
lines changed

11 files changed

+367
-195
lines changed

‎build_tools/circle/build_doc.sh

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ popd
118118
# Using sphinx 1.4 for now until sphinx-gallery has a fix for sphinx 1.5
119119
# See https://github.com/sphinx-gallery/sphinx-gallery/pull/178 for more details
120120
conda create -n testenv --yes --quiet python numpy scipy \
121-
cython nose coverage matplotlib sphinx=1.4 pillow
121+
cython nose coverage matplotlib sphinx pillow
122122
source activate testenv
123123

124124
# Build and install scikit-learn in dev mode

‎doc/sphinxext/sphinx_gallery/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
66
"""
77
import os
8-
__version__ = '0.1.4'
8+
__version__ = '0.1.7'
99

1010

1111
def glr_path_static():

‎doc/sphinxext/sphinx_gallery/_static/gallery.css

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,15 @@ thumbnail with its default link Background color */
103103
blockquote.sphx-glr-script-out {
104104
margin-left: 0pt;
105105
}
106+
107+
div.sphx-glr-footer {
108+
text-align: center;
109+
}
110+
106111
div.sphx-glr-download {
107112
display: inline-block;
108113
margin: 1em auto 1ex 2ex;
114+
vertical-align: middle;
109115
}
110116

111117
div.sphx-glr-download a {
@@ -115,14 +121,45 @@ div.sphx-glr-download a {
115121
border: 1px solid #c2c22d;
116122
color: #000;
117123
display: inline-block;
124+
/* Not valid in old browser, hence we keep the line above to override */
125+
display: table-caption;
118126
font-weight: bold;
119-
max-width: 45ex;
120127
padding: 1ex;
121128
text-align: center;
122129
}
123130

131+
/* The last child of a download button is the file name */
132+
div.sphx-glr-download a span:last-child {
133+
font-size: smaller;
134+
}
135+
136+
@media (min-width: 20em) {
137+
div.sphx-glr-download a {
138+
min-width: 10em;
139+
}
140+
}
141+
142+
@media (min-width: 30em) {
143+
div.sphx-glr-download a {
144+
min-width: 13em;
145+
}
146+
}
147+
148+
@media (min-width: 40em) {
149+
div.sphx-glr-download a {
150+
min-width: 16em;
151+
}
152+
}
153+
154+
124155
div.sphx-glr-download code.download {
125156
display: inline-block;
157+
white-space: normal;
158+
word-break: normal;
159+
overflow-wrap: break-word;
160+
/* border and background are given by the enclosing 'a' */
161+
border: none;
162+
background: none;
126163
}
127164

128165
div.sphx-glr-download a:hover {
@@ -144,10 +181,34 @@ ul.sphx-glr-horizontal img {
144181
}
145182

146183
p.sphx-glr-signature a.reference.external {
147-
background-color: #EBECED;
148184
-moz-border-radius: 5px;
149185
-webkit-border-radius: 5px;
150186
border-radius: 5px;
151187
padding: 3px;
152188
font-size: 75%;
189+
text-align: right;
190+
margin-left: auto;
191+
display: table;
192+
}
193+
194+
a.sphx-glr-code-links:hover{
195+
text-decoration: none;
196+
}
197+
198+
a.sphx-glr-code-links[tooltip]:hover:before{
199+
background: rgba(0,0,0,.8);
200+
border-radius: 5px;
201+
color: white;
202+
content: attr(tooltip);
203+
padding: 5px 15px;
204+
position: absolute;
205+
z-index: 98;
206+
width: 16em;
207+
word-break: normal;
208+
white-space: normal;
209+
display: inline-block;
210+
text-align: center;
211+
text-indent: 0;
212+
margin-left: 0; /* Use zero to avoid overlapping with sidebar */
213+
margin-top: 1.2em;
153214
}

‎doc/sphinxext/sphinx_gallery/backreferences.py

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,13 @@ def identify_names(code):
103103
for name, full_name in finder.get_mapping():
104104
# name is as written in file (e.g. np.asarray)
105105
# full_name includes resolved import path (e.g. numpy.asarray)
106-
module, attribute = full_name.rsplit('.', 1)
106+
splitted = full_name.rsplit('.', 1)
107+
if len(splitted) == 1:
108+
# module without attribute. This is not useful for
109+
# backreferences
110+
continue
111+
112+
module, attribute = splitted
107113
# get shortened module name
108114
module_short = get_short_module_name(module, attribute)
109115
cobj = {'name': attribute, 'module': module,
@@ -127,6 +133,8 @@ def scan_used_functions(example_file, gallery_conf):
127133
return backrefs
128134

129135

136+
# XXX This figure:: uses a forward slash even on Windows, but the op.join's
137+
# elsewhere will use backslashes...
130138
THUMBNAIL_TEMPLATE = """
131139
.. raw:: html
132140

‎doc/sphinxext/sphinx_gallery/docs_resolv.py

Lines changed: 39 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -232,22 +232,34 @@ def _get_link(self, cobj):
232232
fname_idx = value[cobj['name']][0]
233233

234234
if fname_idx is not None:
235-
fname = self._searchindex['filenames'][fname_idx] + '.html'
236-
237-
if self._is_windows:
238-
fname = fname.replace('/', '\\')
239-
link = os.path.join(self.doc_url, fname)
240-
else:
241-
link = posixpath.join(self.doc_url, fname)
242-
243-
if hasattr(link, 'decode'):
244-
link = link.decode('utf-8', 'replace')
245-
246-
if link in self._page_cache:
247-
html = self._page_cache[link]
235+
fname = self._searchindex['filenames'][fname_idx]
236+
# In 1.5+ Sphinx seems to have changed from .rst.html to only
237+
# .html extension in converted files. But URLs could be
238+
# built with < 1.5 or >= 1.5 regardless of what we're currently
239+
# building with, so let's just check both :(
240+
fnames = [fname + '.html', os.path.splitext(fname)[0] + '.html']
241+
for fname in fnames:
242+
try:
243+
if self._is_windows:
244+
fname = fname.replace('/', '\\')
245+
link = os.path.join(self.doc_url, fname)
246+
else:
247+
link = posixpath.join(self.doc_url, fname)
248+
249+
if hasattr(link, 'decode'):
250+
link = link.decode('utf-8', 'replace')
251+
252+
if link in self._page_cache:
253+
html = self._page_cache[link]
254+
else:
255+
html = get_data(link, self.gallery_dir)
256+
self._page_cache[link] = html
257+
except (HTTPError, URLError, IOError):
258+
pass
259+
else:
260+
7802 break
248261
else:
249-
html = get_data(link, self.gallery_dir)
250-
self._page_cache[link] = html
262+
raise
251263

252264
# test if cobj appears in page
253265
comb_names = [cobj['module_short'] + '.' + cobj['name']]
@@ -345,7 +357,8 @@ def _embed_code_links(app, gallery_conf, gallery_dir):
345357
gallery_dir))
346358

347359
# patterns for replacement
348-
link_pattern = '<a href="%s">%s</a>'
360+
link_pattern = ('<a href="%s" class="sphx-glr-code-links" '
361+
'tooltip="Link to documentation for %s">%s</a>')
349362
orig_pattern = '<span class="n">%s</span>'
350363
period = '<span class="o">.</span>'
351364

@@ -374,15 +387,22 @@ def _embed_code_links(app, gallery_conf, gallery_dir):
374387
link = doc_resolvers[this_module].resolve(cobj,
375388
full_fname)
376389
except (HTTPError, URLError) as e:
377-
print("The following error has occurred:\n")
378-
print(repr(e))
390+
if isinstance(e, HTTPError):
391+
extra = e.code
392+
else:
393+
extra = e.reason
394+
print("\t\tError resolving %s.%s: %r (%s)"
395+
% (cobj['module'], cobj['name'], e, extra))
379396
continue
380397

381398
if link is not None:
382399
parts = name.split('.')
383400
name_html = period.join(orig_pattern % part
384401
for part in parts)
385-
str_repl[name_html] = link_pattern % (link, name_html)
402+
full_function_name = '%s.%s' % (
403+
cobj['module'], cobj['name'])
404+
str_repl[name_html] = link_pattern % (
405+
link, full_function_name, name_html)
386406
# do the replacement in the html file
387407

388408
# ensure greediness

‎doc/sphinxext/sphinx_gallery/downloads.py

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,22 +13,26 @@
1313
import zipfile
1414

1515
CODE_DOWNLOAD = """
16-
\n.. container:: sphx-glr-download
16+
\n.. container:: sphx-glr-footer
1717
18-
:download:`Download Python source code: {0} <{0}>`\n
18+
\n .. container:: sphx-glr-download
1919
20-
\n.. container:: sphx-glr-download
20+
:download:`Download Python source code: {0} <{0}>`\n
2121
22-
:download:`Download Jupyter notebook: {1} <{1}>`\n"""
22+
\n .. container:: sphx-glr-download
23+
24+
:download:`Download Jupyter notebook: {1} <{1}>`\n"""
2325

2426
CODE_ZIP_DOWNLOAD = """
25-
\n.. container:: sphx-glr-download
27+
\n.. container:: sphx-glr-footer
28+
29+
\n .. container:: sphx-glr-download
2630
2731
:download:`Download all examples in Python source code: {0} </{1}>`\n
2832
29-
\n.. container:: sphx-glr-download
33+
\n .. container:: sphx-glr-download
3034
31-
:download:`Download all examples in Jupyter notebook files: {2} </{3}>`\n"""
35+
:download:`Download all examples in Jupyter notebooks: {2} </{3}>`\n"""
3236

3337

3438
def python_zip(file_list, gallery_path, extension='.py'):

‎doc/sphinxext/sphinx_gallery/gen_gallery.py

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,12 @@
2020
from .docs_resolv import embed_code_links
2121
from .downloads import generate_zipfiles
2222

23+
try:
24+
FileNotFoundError
25+
except NameError:
26+
# Python2
27+
FileNotFoundError = IOError
28+
2329
DEFAULT_GALLERY_CONF = {
2430
'filename_pattern': re.escape(os.sep) + 'plot',
2531
'examples_dirs': os.path.join('..', 'examples'),
@@ -117,6 +123,10 @@ def generate_gallery_rst(app):
117123
this_fhindex, this_computation_times = \
118124
generate_dir_rst(examples_dir, gallery_dir, gallery_conf,
119125
seen_backrefs)
126+
if this_fhindex == "":
127+
raise FileNotFoundError("Main example directory {0} does not "
128+
"have a README.txt file. Please write "
129+
"one to introduce your gallery.".format(examples_dir))
120130

121131
computation_times += this_computation_times
122132

@@ -178,8 +188,10 @@ def sumarize_failing_examples(app, exception):
178188
return
179189

180190
gallery_conf = app.config.sphinx_gallery_conf
181-
failing_examples = set(gallery_conf['failing_examples'])
182-
expected_failing_examples = set(gallery_conf['expected_failing_examples'])
191+
failing_examples = set([os.path.normpath(path) for path in
192+
gallery_conf['failing_examples']])
193+
expected_failing_examples = set([os.path.normpath(path) for path in
194+
gallery_conf['expected_failing_examples']])
183195

184196
examples_expected_to_fail = failing_examples.intersection(
185197
expected_failing_examples)
@@ -204,7 +216,7 @@ def sumarize_failing_examples(app, exception):
204216
failing_examples)
205217
if examples_not_expected_to_pass:
206218
fail_msgs.append("Examples expected to fail, but not failling:\n" +
207-
"Please remove this examples from\n" +
219+
"Please remove these examples from\n" +
208220
"sphinx_gallery_conf['expected_failing_examples']\n" +
209221
"in your conf.py file"
210222
"\n".join(examples_not_expected_to_pass))

0 commit comments

Comments
 (0)
0