8000 ENH Patches sphinx.ext.autosummary for case insensitive file systems … · thomasjpfan/scikit-learn@8a695d7 · GitHub
[go: up one dir, main page]
Skip to content

Commit 8a695d7

Browse files
thomasjpfanthomasjpfan
authored
ENH Patches sphinx.ext.autosummary for case insensitive file systems (scikit-learn#13022)
* ENH: Patches autosummary for case insensitive file systems * DOC: More details * REV
1 parent 9cf2bac commit 8a695d7

File tree

2 files changed

+96
-1
lines changed

2 files changed

+96
-1
lines changed

‎doc/conf.py

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,8 @@
3939
'sphinx.ext.intersphinx',
4040
'sphinx.ext.imgconverter',
4141
'sphinx_gallery.gen_gallery',
42-
'sphinx_issues'
42+
'sphinx_issues',
43+
'custom_autosummary_new_suffix'
4344
]
4445

4546
# this is needed for some reason...
@@ -410,3 +411,16 @@ def setup(app):
410411
warnings.filterwarnings("ignore", category=UserWarning,
411412
message='Matplotlib is currently using agg, which is a'
412413
' non-GUI backend, so cannot show the figure.')
414+
415+
# Used by custom extension: `custom_autosummary_new_suffix` to change the
416+
# suffix of the following functions. This works around the issue with
417+
# `sklearn.cluster.dbscan` overlapping with `klearn.cluster.DBSCAN` on
418+
# case insensitive file systems.
419+
custom_autosummary_names_with_new_suffix = {
420+
'sklearn.cluster.dbscan',
421+
'sklearn.cluster.optics',
422+
'sklearn.covariance.oas',
423+
'sklearn.decomposition.fastica'
424+
}
425+
custom_autosummary_new_suffix = '-lowercase.rst'
426+
custom_autosummary_generated_dirname = os.path.join('modules', 'generated')

‎doc/sphinxext/custom_autosummary_new_suffix.py

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
"""Patches process_generate_options in sphinx.ext.autosummary to add change
2+
the suffix of items in configuration option
3+
custom_autosummary_names_with_new_suffix to
4+
custom_autosummary_new_suffix. For example:
5+
6+
```python
7+
custom_autosummary_names_with_new_suffix = {
8+
"sklearn.cluster.dbscan",
9+
"sklearn.cluster.optics",
10+
"sklearn.covariance.oas",
11+
"sklearn.decomposition.fastica"
12+
}
13+
custom_autosummary_new_suffix = "-lowercase.rst"
14+
custom_autosummary_generated_dirname = os.path.join('modules', 'generated')
15+
16+
This extension monkeypatches `os.path.join` used by
17+
https://github.com/sphinx-doc/sphinx/blob/7ffd6ccee8b0c6316159c4295e2f44f8c57b90d6/sphinx/ext/autosummary/generate.py#L168
18+
to return a filename with a new suffix.
19+
```
20+
"""
21+
import os
22+
import inspect
23+
from contextlib import contextmanager
24+
25+
from sphinx.ext.autosummary import get_rst_suffix
26+
from sphinx.ext.autosummary import process_generate_options
27+
28+
29+
@contextmanager
30+
def patch_os_path_join(generated_dirname, filename_map):
31+
orig_os_path_join = os.path.join
32+
33+
def custom_os_path_join(a, *p):
34+
path = orig_os_path_join(a, *p)
35+
if len(p) != 1:
36+
return path
37+
38+
dirname, name_with_suffix = os.path.split(path)
39+
if not (dirname.endswith(generated_dirname) and
40+
name_with_suffix in filename_map):
41+
return path
42+
43+
return orig_os_path_join(dirname, filename_map[name_with_suffix])
44+
45+
os.path.join = custom_os_path_join
46+
yield
47+
os.path.join = orig_os_path_join
48+
49+
50+
def process_generate_options_custom_files(app):
51+
52+
orig_suffix = get_rst_suffix(app)
53+
new_suffix = app.config.custom_autosummary_new_suffix
54+
generated_dirname = app.config.custom_autosummary_generated_dirname
55+
filename_map = {
56+
name + orig_suffix: name + new_suffix
57+
for name in app.config.custom_autosummary_names_with_new_suffix
58+
}
59+
60+
with patch_os_path_join(generated_dirname, filename_map):
61+
process_generate_options(app)
62+
63+
64+
def setup(app):
65+
app.setup_extension('sphinx.ext.autosummary')
66+
app.add_config_value(
67+
'custom_autosummary_names_with_new_suffix', set(), None)
68+
app.add_config_value(
69+
'custom_autosummary_new_suffix', '-lowercase.rst', None)
70+
app.add_config_value(
71+
'custom_autosummary_generated_dirname', '', None)
72+
73+
# Override process_generate_options added by sphinx.ext.autosummary
74+
builder_inited_listeners = app.events.listeners["builder-inited"]
75+
76+
for listener_id, obj in builder_inited_listeners.items():
77+
if (inspect.isfunction(obj)
78+
and obj.__name__ == "process_generate_options"):
79+
builder_inited_listeners[listener_id] = \
80+
process_generate_options_custom_files
81+
break

0 commit comments

Comments
 (0)
0