1 | """ help.py: Implement the Idle help menu. |
---|
2 | Contents are subject to revision at any time, without notice. |
---|
3 | |
---|
4 | |
---|
5 | Help => About IDLE: diplay About Idle dialog |
---|
6 | |
---|
7 | <to be moved here from aboutDialog.py> |
---|
8 | |
---|
9 | |
---|
10 | Help => IDLE Help: Display help.html with proper formatting. |
---|
11 | Doc/library/idle.rst (Sphinx)=> Doc/build/html/library/idle.html |
---|
12 | (help.copy_strip)=> Lib/idlelib/help.html |
---|
13 | |
---|
14 | HelpParser - Parse help.html and render to tk Text. |
---|
15 | |
---|
16 | HelpText - Display formatted help.html. |
---|
17 | |
---|
18 | HelpFrame - Contain text, scrollbar, and table-of-contents. |
---|
19 | (This will be needed for display in a future tabbed window.) |
---|
20 | |
---|
21 | HelpWindow - Display HelpFrame in a standalone window. |
---|
22 | |
---|
23 | copy_strip - Copy idle.html to help.html, rstripping each line. |
---|
24 | |
---|
25 | show_idlehelp - Create HelpWindow. Called in EditorWindow.help_dialog. |
---|
26 | """ |
---|
27 | from HTMLParser import HTMLParser |
---|
28 | from os.path import abspath, dirname, isdir, isfile, join |
---|
29 | from Tkinter import Tk, Toplevel, Frame, Text, Scrollbar, Menu, Menubutton |
---|
30 | import tkFont as tkfont |
---|
31 | from idlelib.configHandler import idleConf |
---|
32 | |
---|
33 | use_ttk = False # until available to import |
---|
34 | if use_ttk: |
---|
35 | from tkinter.ttk import Menubutton |
---|
36 | |
---|
37 | ## About IDLE ## |
---|
38 | |
---|
39 | |
---|
40 | ## IDLE Help ## |
---|
41 | |
---|
42 | class HelpParser(HTMLParser): |
---|
43 | """Render help.html into a text widget. |
---|
44 | |
---|
45 | The overridden handle_xyz methods handle a subset of html tags. |
---|
46 | The supplied text should have the needed tag configurations. |
---|
47 | The behavior for unsupported tags, such as table, is undefined. |
---|
48 | If the tags generated by Sphinx change, this class, especially |
---|
49 | the handle_starttag and handle_endtags methods, might have to also. |
---|
50 | """ |
---|
51 | def __init__(self, text): |
---|
52 | HTMLParser.__init__(self) |
---|
53 | self.text = text # text widget we're rendering into |
---|
54 | self.tags = '' # current block level text tags to apply |
---|
55 | self.chartags = '' # current character level text tags |
---|
56 | self.show = False # used so we exclude page navigation |
---|
57 | self.hdrlink = False # used so we don't show header links |
---|
58 | self.level = 0 # indentation level |
---|
59 | self.pre = False # displaying preformatted text |
---|
60 | self.hprefix = '' # prefix such as '25.5' to strip from headings |
---|
61 | self.nested_dl = False # if we're in a nested <dl> |
---|
62 | self.simplelist = False # simple list (no double spacing) |
---|
63 | self.toc = [] # pair headers with text indexes for toc |
---|
64 | self.header = '' # text within header tags for toc |
---|
65 | |
---|
66 | def indent(self, amt=1): |
---|
67 | self.level += amt |
---|
68 | self.tags = '' if self.level == 0 else 'l'+str(self.level) |
---|
69 | |
---|
70 | def handle_starttag(self, tag, attrs): |
---|
71 | "Handle starttags in help.html." |
---|
72 | class_ = '' |
---|
73 | for a, v in attrs: |
---|
74 | if a == 'class': |
---|
75 | class_ = v |
---|
76 | s = '' |
---|
77 | if tag == 'div' and class_ == 'section': |
---|
78 | self.show = True # start of main content |
---|
79 | elif tag == 'div' and class_ == 'sphinxsidebar': |
---|
80 | self.show = False # end of main content |
---|
81 | elif tag == 'p' and class_ != 'first': |
---|
82 | s = '\n\n' |
---|
83 | elif tag == 'span' and class_ == 'pre': |
---|
84 | self.chartags = 'pre' |
---|
85 | elif tag == 'span' and class_ == 'versionmodified': |
---|
86 | self.chartags = 'em' |
---|
87 | elif tag == 'em': |
---|
88 | self.chartags = 'em' |
---|
89 | elif tag in ['ul', 'ol']: |
---|
90 | if class_.find('simple') != -1: |
---|
91 | s = '\n' |
---|
92 | self.simplelist = True |
---|
93 | else: |
---|
94 | self.simplelist = False |
---|
95 | self.indent() |
---|
96 | elif tag == 'dl': |
---|
97 | if self.level > 0: |
---|
98 | self.nested_dl = True |
---|
99 | elif tag == 'li': |
---|
100 | s = '\n* ' if self.simplelist else '\n\n* ' |
---|
101 | elif tag == 'dt': |
---|
102 | s = '\n\n' if not self.nested_dl else '\n' # avoid extra line |
---|
103 | self.nested_dl = False |
---|
104 | elif tag == 'dd': |
---|
105 | self.indent() |
---|
106 | s = '\n' |
---|
107 | elif tag == 'pre': |
---|
108 | self.pre = True |
---|
109 | if self.show: |
---|
110 | self.text.insert('end', '\n\n') |
---|
111 | self.tags = 'preblock' |
---|
112 | elif tag == 'a' and class_ == 'headerlink': |
---|
113 | self.hdrlink = True |
---|
114 | elif tag == 'h1': |
---|
115 | self.tags = tag |
---|
116 | elif tag in ['h2', 'h3']: |
---|
117 | if self.show: |
---|
118 | self.header = '' |
---|
119 | self.text.insert('end', '\n\n') |
---|
120 | self.tags = tag |
---|
121 | if self.show: |
---|
122 | self.text.insert('end', s, (self.tags, self.chartags)) |
---|
123 | |
---|
124 | def handle_endtag(self, tag): |
---|
125 | "Handle endtags in help.html." |
---|
126 | if tag in ['h1', 'h2', 'h3']: |
---|
127 | self.indent(0) # clear tag, reset indent |
---|
128 | if self.show: |
---|
129 | self.toc.append((self.header, self.text.index('insert'))) |
---|
130 | elif tag in ['span', 'em']: |
---|
131 | self.chartags = '' |
---|
132 | elif tag == 'a': |
---|
133 | self.hdrlink = False |
---|
134 | elif tag == 'pre': |
---|
135 | self.pre = False |
---|
136 | self.tags = '' |
---|
137 | elif tag in ['ul', 'dd', 'ol']: |
---|
138 | self.indent(amt=-1) |
---|
139 | |
---|
140 | def handle_data(self, data): |
---|
141 | "Handle date segments in help.html." |
---|
142 | if self.show and not self.hdrlink: |
---|
143 | d = data if self.pre else data.replace('\n', ' ') |
---|
144 | if self.tags == 'h1': |
---|
145 | self.hprefix = d[0:d.index(' ')] |
---|
146 | if self.tags in ['h1', 'h2', 'h3'] and self.hprefix != '': |
---|
147 | if d[0:len(self.hprefix)] == self.hprefix: |
---|
148 | d = d[len(self.hprefix):].strip() |
---|
149 | self.header += d |
---|
150 | self.text.insert('end', d, (self.tags, self.chartags)) |
---|
151 | |
---|
152 | def handle_charref(self, name): |
---|
153 | self.text.insert('end', unichr(int(name))) |
---|
154 | |
---|
155 | |
---|
156 | class HelpText(Text): |
---|
157 | "Display help.html." |
---|
158 | def __init__(self, parent, filename): |
---|
159 | "Configure tags and feed file to parser." |
---|
160 | uwide = idleConf.GetOption('main', 'EditorWindow', 'width', type='int') |
---|
161 | uhigh = idleConf.GetOption('main', 'EditorWindow', 'height', type='int') |
---|
162 | uhigh = 3 * uhigh // 4 # lines average 4/3 of editor line height |
---|
163 | Text.__init__(self, parent, wrap='word', highlightthickness=0, |
---|
164 | padx=5, borderwidth=0, width=uwide, height=uhigh) |
---|
165 | |
---|
166 | normalfont = self.findfont(['TkDefaultFont', 'arial', 'helvetica']) |
---|
167 | fixedfont = self.findfont(['TkFixedFont', 'monaco', 'courier']) |
---|
168 | self['font'] = (normalfont, 12) |
---|
169 | self.tag_configure('em', font=(normalfont, 12, 'italic')) |
---|
170 | self.tag_configure('h1', font=(normalfont, 20, 'bold')) |
---|
171 | self.tag_configure('h2', font=(normalfont, 18, 'bold')) |
---|
172 | self.tag_configure('h3', font=(normalfont, 15, 'bold')) |
---|
173 | self.tag_configure('pre', font=(fixedfont, 12), background='#f6f6ff') |
---|
174 | self.tag_configure('preblock', font=(fixedfont, 10), lmargin1=25, |
---|
175 | borderwidth=1, relief='solid', background='#eeffcc') |
---|
176 | self.tag_configure('l1', lmargin1=25, lmargin2=25) |
---|
177 | self.tag_configure('l2', lmargin1=50, lmargin2=50) |
---|
178 | self.tag_configure('l3', lmargin1=75, lmargin2=75) |
---|
179 | self.tag_configure('l4', lmargin1=100, lmargin2=100) |
---|
180 | |
---|
181 | self.parser = HelpParser(self) |
---|
182 | with open(filename) as f: |
---|
183 | contents = f.read().decode(encoding='utf-8') |
---|
184 | self.parser.feed(contents) |
---|
185 | self['state'] = 'disabled' |
---|
186 | |
---|
187 | def findfont(self, names): |
---|
188 | "Return name of first font family derived from names." |
---|
189 | for name in names: |
---|
190 | if name.lower() in (x.lower() for x in tkfont.names(root=self)): |
---|
191 | font = tkfont.Font(name=name, exists=True, root=self) |
---|
192 | return font.actual()['family'] |
---|
193 | elif name.lower() in (x.lower() |
---|
194 | for x in tkfont.families(root=self)): |
---|
195 | return name |
---|
196 | |
---|
197 | |
---|
198 | class HelpFrame(Frame): |
---|
199 | "Display html text, scrollbar, and toc." |
---|
200 | def __init__(self, parent, filename): |
---|
201 | Frame.__init__(self, parent) |
---|
202 | text = HelpText(self, filename) |
---|
203 | self['background'] = text['background'] |
---|
204 | scroll = Scrollbar(self, command=text.yview) |
---|
205 | text['yscrollcommand'] = scroll.set |
---|
206 | self.rowconfigure(0, weight=1) |
---|
207 | self.columnconfigure(1, weight=1) # text |
---|
208 | self.toc_menu(text).grid(column=0, row=0, sticky='nw') |
---|
209 | text.grid(column=1, row=0, sticky='nsew') |
---|
210 | scroll.grid(column=2, row=0, sticky='ns') |
---|
211 | |
---|
212 | def toc_menu(self, text): |
---|
213 | "Create table of contents as drop-down menu." |
---|
214 | toc = Menubutton(self, text='TOC') |
---|
215 | drop = Menu(toc, tearoff=False) |
---|
216 | for lbl, dex in text.parser.toc: |
---|
217 | drop.add_command(label=lbl, command=lambda dex=dex:text.yview(dex)) |
---|
218 | toc['menu'] = drop |
---|
219 | return toc |
---|
220 | |
---|
221 | |
---|
222 | class HelpWindow(Toplevel): |
---|
223 | "Display frame with rendered html." |
---|
224 | def __init__(self, parent, filename, title): |
---|
225 | Toplevel.__init__(self, parent) |
---|
226 | self.wm_title(title) |
---|
227 | self.protocol("WM_DELETE_WINDOW", self.destroy) |
---|
228 | HelpFrame(self, filename).grid(column=0, row=0, sticky='nsew') |
---|
229 | self.grid_columnconfigure(0, weight=1) |
---|
230 | self.grid_rowconfigure(0, weight=1) |
---|
231 | |
---|
232 | |
---|
233 | def copy_strip(): |
---|
234 | """Copy idle.html to idlelib/help.html, stripping trailing whitespace. |
---|
235 | |
---|
236 | Files with trailing whitespace cannot be pushed to the hg cpython |
---|
237 | repository. For 3.x (on Windows), help.html is generated, after |
---|
238 | editing idle.rst in the earliest maintenance version, with |
---|
239 | sphinx-build -bhtml . build/html |
---|
240 | python_d.exe -c "from idlelib.help import copy_strip; copy_strip()" |
---|
241 | After refreshing TortoiseHG workshop to generate a diff, |
---|
242 | check both the diff and displayed text. Push the diff along with |
---|
243 | the idle.rst change and merge both into default (or an intermediate |
---|
244 | maintenance version). |
---|
245 | |
---|
246 | When the 'earlist' version gets its final maintenance release, |
---|
247 | do an update as described above, without editing idle.rst, to |
---|
248 | rebase help.html on the next version of idle.rst. Do not worry |
---|
249 | about version changes as version is not displayed. Examine other |
---|
250 | changes and the result of Help -> IDLE Help. |
---|
251 | |
---|
252 | If maintenance and default versions of idle.rst diverge, and |
---|
253 | merging does not go smoothly, then consider generating |
---|
254 | separate help.html files from separate idle.htmls. |
---|
255 | """ |
---|
256 | src = join(abspath(dirname(dirname(dirname(__file__)))), |
---|
257 | 'Doc', 'build', 'html', 'library', 'idle.html') |
---|
258 | dst = join(abspath(dirname(__file__)), 'help.html') |
---|
259 | with open(src, 'r') as inn,\ |
---|
260 | open(dst, 'w') as out: |
---|
261 | for line in inn: |
---|
262 | out.write(line.rstrip() + '\n') |
---|
263 | print('idle.html copied to help.html') |
---|
264 | |
---|
265 | def show_idlehelp(parent): |
---|
266 | "Create HelpWindow; called from Idle Help event handler." |
---|
267 | filename = join(abspath(dirname(__file__)), 'help.html') |
---|
268 | if not isfile(filename): |
---|
269 | # try copy_strip, present message |
---|
270 | return |
---|
271 | HelpWindow(parent, filename, 'IDLE Help') |
---|
272 | |
---|
273 | if __name__ == '__main__': |
---|
274 | from idlelib.idle_test.htest import run |
---|
275 | run(show_idlehelp) |
---|