""" help.py: Implement the Idle help menu.

Contents are subject to revision at any time, without notice.

Help => About IDLE: diplay About Idle dialog

<to be moved here from aboutDialog.py>

Help => IDLE Help: Display help.html with proper formatting.

Doc/library/idle.rst (Sphinx)=> Doc/build/html/library/idle.html

(help.copy_strip)=> Lib/idlelib/help.html

HelpParser - Parse help.html and and render to tk Text.

HelpText - Display formatted help.html.

HelpFrame - Contain text, scrollbar, and table-of-contents.

(This will be needed for display in a future tabbed window.)

HelpWindow - Display HelpFrame in a standalone window.

copy_strip - Copy idle.html to help.html, rstripping each line.

show_idlehelp - Create HelpWindow. Called in EditorWindow.help_dialog.

"""

from html.parser import HTMLParser

from os.path import abspath, dirname, isdir, isfile, join

from tkinter import Tk, Toplevel, Frame, Text, Scrollbar, Menu, Menubutton

from tkinter import font as tkfont

use_ttk = False # until available to import

if use_ttk:

from tkinter.ttk import Menubutton

## About IDLE ##

## IDLE Help ##

class HelpParser(HTMLParser):

"""Render help.html into a text widget.

The overridden handle_xyz methods handle a subset of html tags.

The supplied text should have the needed tag configurations.

The behavior for unsupported tags, such as table, is undefined.

"""

def __init__(self, text):

HTMLParser.__init__(self, convert_charrefs=True)

self.text = text # text widget we're rendering into

self.tags = '' # current text tags to apply

self.show = False # used so we exclude page navigation

self.hdrlink = False # used so we don't show header links

self.level = 0 # indentation level

self.pre = False # displaying preformatted text

self.hprefix = '' # strip e.g. '25.5' from headings

self.nested_dl = False # if we're in a nested <dl>

self.simplelist = False # simple list (no double spacing)

self.tocid = 1 # id for table of contents entries

self.contents = [] # map toc ids to section titles

self.data = '' # to record data within header tags for toc

def indent(self, amt=1):

self.level += amt

self.tags = '' if self.level == 0 else 'l'+str(self.level)

def handle_starttag(self, tag, attrs):

"Handle starttags in help.html."

class_ = ''

for a, v in attrs:

if a == 'class':

class_ = v

s = ''

if tag == 'div' and class_ == 'section':

self.show = True # start of main content

elif tag == 'div' and class_ == 'sphinxsidebar':

self.show = False # end of main content

elif tag == 'p' and class_ != 'first':

s = '\n\n'

elif tag == 'span' and class_ == 'pre':

self.tags = 'pre'

elif tag == 'span' and class_ == 'versionmodified':

self.tags = 'em'

elif tag == 'em':

self.tags = 'em'

elif tag in ['ul', 'ol']:

if class_.find('simple') != -1:

s = '\n'

self.simplelist = True

else:

self.simplelist = False

self.indent()

elif tag == 'dl':

if self.level > 0:

self.nested_dl = True

elif tag == 'li':

s = '\n* ' if self.simplelist else '\n\n* '

elif tag == 'dt':

s = '\n\n' if not self.nested_dl else '\n' # avoid extra line

self.nested_dl = False

elif tag == 'dd':

self.indent()

s = '\n'

elif tag == 'pre':

self.pre = True

if self.show:

self.text.insert('end', '\n\n')

self.tags = 'preblock'

elif tag == 'a' and class_ == 'headerlink':

self.hdrlink = True

elif tag == 'h1':

self.text.mark_set('toc'+str(self.tocid),

self.text.index('end-1line'))

self.tags = tag

elif tag in ['h2', 'h3']:

if self.show:

self.data = ''

self.text.mark_set('toc'+str(self.tocid),

self.text.index('end-1line'))

self.text.insert('end', '\n\n')

self.tags = tag

if self.show:

self.text.insert('end', s, self.tags)

def handle_endtag(self, tag):

"Handle endtags in help.html."

if tag in ['h1', 'h2', 'h3', 'span', 'em']:

self.indent(0) # clear tag, reset indent

if self.show and tag in ['h1', 'h2', 'h3']:

title = self.data

self.contents.append(('toc'+str(self.tocid), title))

self.tocid += 1

elif tag == 'a':

self.hdrlink = False

elif tag == 'pre':

self.pre = False

self.tags = ''

elif tag in ['ul', 'dd', 'ol']:

self.indent(amt=-1)

def handle_data(self, data):

"Handle date segments in help.html."

if self.show and not self.hdrlink:

d = data if self.pre else data.replace('\n', ' ')

if self.tags == 'h1':

self.hprefix = d[0:d.index(' ')]

if self.tags in ['h1', 'h2', 'h3'] and self.hprefix != '':

if d[0:len(self.hprefix)] == self.hprefix:

d = d[len(self.hprefix):].strip()

self.data += d

self.text.insert('end', d, self.tags)

class HelpText(Text):

"Display help.html."

def __init__(self, parent, filename):

"Configure tags and feed file to parser."

Text.__init__(self, parent, wrap='word', highlightthickness=0,

padx=5, borderwidth=0)

normalfont = self.findfont(['TkDefaultFont', 'arial', 'helvetica'])

fixedfont = self.findfont(['TkFixedFont', 'monaco', 'courier'])

self['font'] = (normalfont, 12)

self.tag_configure('em', font=(normalfont, 12, 'italic'))

self.tag_configure('h1', font=(normalfont, 20, 'bold'))

self.tag_configure('h2', font=(normalfont, 18, 'bold'))

self.tag_configure('h3', font=(normalfont, 15, 'bold'))

self.tag_configure('pre', font=(fixedfont, 12))

self.tag_configure('preblock', font=(fixedfont, 10), lmargin1=25,

borderwidth=1, relief='solid', background='#eeffcc')

self.tag_configure('l1', lmargin1=25, lmargin2=25)

self.tag_configure('l2', lmargin1=50, lmargin2=50)

self.tag_configure('l3', lmargin1=75, lmargin2=75)

self.tag_configure('l4', lmargin1=100, lmargin2=100)

self.parser = HelpParser(self)

with open(filename, encoding='utf-8') as f:

contents = f.read()

self.parser.feed(contents)

self['state'] = 'disabled'

def findfont(self, names):

"Return name of first font family derived from names."

for name in names:

if name.lower() in (x.lower() for x in tkfont.names(root=self)):

font = tkfont.Font(name=name, exists=True, root=self)

return font.actual()['family']

elif name.lower() in (x.lower()

for x in tkfont.families(root=self)):

return name

class HelpFrame(Frame):

"Display html text, scrollbar, and toc."

def __init__(self, parent, filename):

Frame.__init__(self, parent)

text = HelpText(self, filename)

self['background'] = text['background']

scroll = Scrollbar(self, command=text.yview)

text['yscrollcommand'] = scroll.set

text.grid(column=1, row=0, sticky='nsew')

scroll.grid(column=2, row=0, sticky='ns')

self.grid_columnconfigure(1, weight=1)

self.grid_rowconfigure(0, weight=1)

toc = self.contents_widget(text)

toc.grid(column=0, row=0, sticky='nw')

def contents_widget(self, text):

"Create table of contents."

toc = Menubutton(self, text='TOC')

drop = Menu(toc, tearoff=False)

for tag, lbl in text.parser.contents:

drop.add_command(label=lbl, command=lambda mark=tag:text.see(mark))

toc['menu'] = drop

return toc

class HelpWindow(Toplevel):

"Display frame with rendered html."

def __init__(self, parent, filename, title):

Toplevel.__init__(self, parent)

self.wm_title(title)

self.protocol("WM_DELETE_WINDOW", self.destroy)

HelpFrame(self, filename).grid(column=0, row=0, sticky='nsew')

self.grid_columnconfigure(0, weight=1)

self.grid_rowconfigure(0, weight=1)

def copy_strip():

"Copy idle.html to idlelib/help.html, stripping trailing whitespace."

src = join(abspath(dirname(dirname(dirname(__file__)))),

'Doc', 'build', 'html', 'library', 'idle.html')

dst = join(abspath(dirname(__file__)), 'help.html')

with open(src, 'rb') as inn,\

open(dst, 'wb') as out:

for line in inn:

out.write(line.rstrip() + '\n')

print('idle.html copied to help.html')

def show_idlehelp(parent):

"Create HelpWindow; called from Idle Help event handler."

filename = join(abspath(dirname(__file__)), 'help.html')

if not isfile(filename):

# try copy_strip, present message

return

HelpWindow(parent, filename, 'IDLE Help')

if __name__ == '__main__':

from idlelib.idle_test.htest import run

run(show_idlehelp)