Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2"""
3@file
4@brief Various helpers for Sphinx.
5"""
6import os
7from ..filehelper import synchronize_folder, explore_folder_iterfile
8from ..loghelper.flog import noLOG, fLOG
11def everything_but_python(fullname):
12 """
13 Returns True if ``__pycache__`` is not in filename.
14 """
15 if "__pycache__" in fullname:
16 return False
17 return os.path.splitext(fullname)[-1] not in [".py", ".pyc"]
20def sphinx_add_scripts(source, dest, filter=everything_but_python, fLOG=fLOG):
21 """
22 copy additional scripts to a folder for sphinx documentation
24 @param source source
25 @param dest destination folder (will be created if it does not exists)
26 @param filter @see fn synchronize_folder
27 @param fLOG logging function
28 @return @see fn synchronize_folder
29 """
31 if not os.path.exists(dest):
32 os.makedirs(dest)
34 res = synchronize_folder(
35 source, dest, repo1=False, repo2=False, filter=filter, fLOG=fLOG)
36 return res
39def post_process_html_nb_output_static_file(build, fLOG=noLOG):
40 """
41 post process the HTML files produced by Sphinx to adjust the static files
42 in notebooks (IPython static files do have the same paths as
43 Sphinx static files)
45 @param build build location
46 @param fLOG logging function
47 @return list of modified files
49 Static path in IPython start by ``/static``, they start by ``../_static``
50 or ``/_static`` in Sphinx.
51 """
52 if not os.path.exists(build):
53 raise FileNotFoundError(build)
55 tofind = ' src="/static/'
56 torep = ' src="../_static/'
58 res = []
59 for full in explore_folder_iterfile(build, pattern=".*[.]html"):
60 modif = False
61 with open(full, "r", encoding="utf8") as f:
62 try:
63 content = f.read()
64 except UnicodeDecodeError as e:
65 # maybe it is Windows and the encoding is sometimes different
66 with open(full, "r", encoding="cp1252") as g:
67 try:
68 content = g.read()
69 content = content.replace(
70 "charset=cp1252", "charset=utf-8")
71 except UnicodeDecodeError:
72 raise FileNotFoundError(
73 "Unable to load %r\n%r" % (full, os.path.abspath(full))) from e
75 if tofind in content:
76 res.append(full)
77 content = content.replace(tofind, torep)
78 modif = True
80 # js
81 repl = {'https://unpkg.com/@jupyter-widgets/html-manager@^0.20.0/dist/embed-amd.js':
82 '../_static/embed-amd.js'}
83 lines = content.split('\n')
84 new_lines = []
85 for line in lines:
86 if "https://cdnjs.cloudflare.com/ajax/libs/require.js" in line:
87 if fLOG:
88 fLOG(
89 "[post_process_html_nb_output_static_file] js: skip %r" % line)
90 modif = True
91 continue
92 new_lines.append(line)
93 content = "\n".join(new_lines)
94 for k, v in repl.items():
95 if k in content:
96 if fLOG:
97 fLOG("[post_process_html_output] js: replace %r -> %r" % (k, v))
98 content = content.replace(k, v)
99 modif = True
101 if modif:
102 fLOG("[post_process_html_nb_output_static_file] %r" % full)
103 with open(full, "w", encoding="utf8") as f:
104 f.write(content)
106 return res