def BuildEnumsAndMethods(sphinxDir):
"""
This function does some clean-up/refactoring of the generated ReST files by:
1. Removing the `:meth:` reference to Enums, as they are not methods, and replacing
it with the `:ref:` role. This information is unfortunately not known when the
main `etgtools/sphinx_generator.py` runs.
2. Removing the "Perl note" stuff from the text (and we should clean up the
wxWidgets docs at the source to remove the wxPython notes as well).
3. Substituting the `:ref:` role for unreferenced classes (these may be classes yet
to be ported to Phoenix or C++-specific classes which will never be ported to
Phoenix) with simple backticks.
4. Some cleanup.
"""
fid = open(os.path.join(sphinxDir, 'class_summary.lst'), 'rb')
class_summary = pickle.load(fid)
fid.close()
unreferenced_classes = {}
textfiles = glob.glob(sphinxDir + '/*.txt')
enum_files = glob.glob(sphinxDir + '/*.enumeration.txt')
enum_base = [os.path.split(os.path.splitext(enum)[0])[1] for enum in enum_files]
enum_base = [enum.replace('.enumeration', '') for enum in enum_base]
enum_dict = {}
for enum in enum_base:
enum_dict[':meth:`%s`'%enum] = ':ref:`%s`'%enum
for input in textfiles:
fid = textfile_open(input, 'rt')
orig_text = text = fid.read()
fid.close()
for old, new in list(enum_dict.items()):
text = text.replace(old, new)
widget_name = os.path.split(os.path.splitext(input)[0])[1]
if widget_name in SECTIONS_EXCLUDE:
start, end = SECTIONS_EXCLUDE[widget_name]
if start in text and end in text:
lindex = text.index(start)
rindex = text.index(end)
text = text[0:lindex] + text[rindex:]
# Replace the "Perl Note" stuff, we don't need it
newtext = ''
for line in text.splitlines():
if 'perl note' in line.lower():
continue
newtext += line + '\n'
text = newtext
text = FindInherited(input, class_summary, enum_base, text)
text, unreferenced_classes = RemoveUnreferenced(input, class_summary, enum_base, unreferenced_classes, text)
text = text.replace('wx``', '``')
text = text.replace('wx.``', '``')
text = text.replace('non-NULL', 'not ``None``')
text = text.replace(',,', ',').replace(', ,', ',')
text = text.replace('|wx', '|')
# Replacements for ScrolledWindow and ScrolledCanvas...
text = text.replace('<wxWindow>', 'Window')
text = text.replace('<wxPanel>', 'Panel')
# Replacement for wx.grid stuff
text = text.replace(' int *,', ' int,')
if 'DocstringsGuidelines' not in input:
# Leave the DocstringsGuidelines.txt file alone on these ones
text = text.replace(':note:', '.. note::')
text = text.replace(':see:', '.. seealso::')
text = text.replace('`String`&', 'string')
text = text.replace('See also\n', '.. seealso:: ')
# Avoid Sphinx warnings on wx.TreeCtrl
text = text.replace('**( `', '** ( `')
# Replace EmptyString stuff
for item in ['wx.EmptyString', 'EmptyString']:
text = text.replace(item, '""')
# Replace ArrayXXX stuff...
for cpp in ['ArrayString()', 'ArrayInt()', 'ArrayDouble()', 'ArrayString']:
text = text.replace(cpp, '[]')
# Remove lines with "Event macros" in them...
text = text.replace('Event macros:', '')
text = TooltipsOnInheritance(text, class_summary)
text = AddSpacesToLinks(text)
if text != orig_text:
fid = textfile_open(input, 'wt')
fid.write(text)
fid.close()
if not unreferenced_classes:
return
warn = '\n\nWARNING: there are %d instances of referenced classes/enums, via the `:ref:` role, which\n' \
'are not in the list of available classes (these may be classes yet to be ported to Phoenix\n' \
'or C++-specific classes which will never be ported to Phoenix).\n\n' \
'*sphinxgenerator* has replaced the `:ref:` role for them with simple backticks, i.e.:\n\n' \
' :ref:`MissingClass` ==> `MissingClass`\n\n' \
'to avoid warning from Sphinx and Docutils, and saved a list of their occurrences into\n' \
'the text file "unreferenced_classes.inc" together with the ReST file names where they\n' \
'appear.\n\n'
keys = list(unreferenced_classes.keys())
keys.sort()
fid = textfile_open(os.path.join(SPHINXROOT, 'unreferenced_classes.inc'), 'wt')
fid.write('\n')
fid.write('='*50 + ' ' + '='*50 + '\n')
fid.write('%-50s %-50s\n'%('Reference', 'File Name(s)'))
fid.write('='*50 + ' ' + '='*50 + '\n')
for key in keys:
fid.write('%-50s %-50s\n'%(key, ', '.join(unreferenced_classes[key])))
fid.write('='*50 + ' ' + '='*50 + '\n')
fid.close()
print((warn%(len(keys))))
def BuildEnumsAndMethods(sphinxDir):
"""
This function does some clean-up/refactoring of the generated ReST files by:
1. Removing the `:meth:` reference to Enums, as they are not methods, and replacing
it with the `:ref:` role. This information is unfortunately not known when the
main `etgtools/sphinx_generator.py` runs.
2. Removing the "Perl note" stuff from the text (and we should clean up the
wxWidgets docs at the source to remove the wxPython notes as well).
3. Substituting the `:ref:` role for unreferenced classes (these may be classes yet
to be ported to Phoenix or C++-specific classes which will never be ported to
Phoenix) with simple backticks.
4. Some cleanup.
"""
fid = open(os.path.join(sphinxDir, "class_summary.lst"), "rb")
class_summary = pickle.load(fid)
fid.close()
unreferenced_classes = {}
textfiles = glob.glob(sphinxDir + "/*.txt")
enum_files = glob.glob(sphinxDir + "/*.enumeration.txt")
enum_base = [os.path.split(os.path.splitext(enum)[0])[1] for enum in enum_files]
enum_base = [enum.replace(".enumeration", "") for enum in enum_base]
enum_dict = {}
for enum in enum_base:
enum_dict[":meth:`%s`" % enum] = ":ref:`%s`" % enum
for input in textfiles:
fid = textfile_open(input, "rt")
orig_text = text = fid.read()
fid.close()
for old, new in list(enum_dict.items()):
text = text.replace(old, new)
widget_name = os.path.split(os.path.splitext(input)[0])[1]
if widget_name in SECTIONS_EXCLUDE:
start, end = SECTIONS_EXCLUDE[widget_name]
if start in text and end in text:
lindex = text.index(start)
rindex = text.index(end)
text = text[0:lindex] + text[rindex:]
# Replace the "Perl Note" stuff, we don't need it
newtext = ""
for line in text.splitlines():
if "perl note" in line.lower():
continue
newtext += line + "\n"
text = newtext
text = FindInherited(input, class_summary, enum_base, text)
text, unreferenced_classes = RemoveUnreferenced(input, class_summary, enum_base, unreferenced_classes, text)
text = text.replace("wx``", "``")
text = text.replace("wx.``", "``")
text = text.replace("non-NULL", "not ``None``")
text = text.replace(",,", ",").replace(", ,", ",")
text = text.replace("|wx", "|")
# Replacements for ScrolledWindow and ScrolledCanvas...
text = text.replace("<wxWindow>", "Window")
text = text.replace("<wxPanel>", "Panel")
# Replacement for wx.grid stuff
text = text.replace(" int *,", " int,")
if "DocstringsGuidelines" not in input:
# Leave the DocstringsGuidelines.txt file alone on these ones
text = text.replace(":note:", ".. note::")
text = text.replace(":see:", ".. seealso::")
text = text.replace("`String`&", "string")
text = text.replace("See also\n", ".. seealso:: ")
# Avoid Sphinx warnings on wx.TreeCtrl
text = text.replace("**( `", "** ( `")
# Replace EmptyString stuff
for item in ["wx.EmptyString", "EmptyString"]:
text = text.replace(item, '""')
# Replace ArrayXXX stuff...
for cpp in ["ArrayString()", "ArrayInt()", "ArrayDouble()", "ArrayString"]:
text = text.replace(cpp, "[]")
# Remove lines with "Event macros" in them...
text = text.replace("Event macros:", "")
text = TooltipsOnInheritance(text, class_summary)
text = AddSpacesToLinks(text)
if text != orig_text:
fid = textfile_open(input, "wt")
fid.write(text)
fid.close()
if not unreferenced_classes:
return
warn = (
"\n\nWARNING: there are %d instances of referenced classes/enums, via the `:ref:` role, which\n"
"are not in the list of available classes (these may be classes yet to be ported to Phoenix\n"
"or C++-specific classes which will never be ported to Phoenix).\n\n"
"*sphinxgenerator* has replaced the `:ref:` role for them with simple backticks, i.e.:\n\n"
" :ref:`MissingClass` ==> `MissingClass`\n\n"
"to avoid warning from Sphinx and Docutils, and saved a list of their occurrences into\n"
'the text file "unreferenced_classes.inc" together with the ReST file names where they\n'
"appear.\n\n"
)
keys = list(unreferenced_classes.keys())
keys.sort()
fid = textfile_open(os.path.join(SPHINXROOT, "unreferenced_classes.inc"), "wt")
fid.write("\n")
fid.write("=" * 50 + " " + "=" * 50 + "\n")
fid.write("%-50s %-50s\n" % ("Reference", "File Name(s)"))
fid.write("=" * 50 + " " + "=" * 50 + "\n")
for key in keys:
fid.write("%-50s %-50s\n" % (key, ", ".join(unreferenced_classes[key])))
fid.write("=" * 50 + " " + "=" * 50 + "\n")
fid.close()
print((warn % (len(keys))))
def postProcess(folder, options):
fileNames = glob.glob(folder + "/*.html")
enum_files = glob.glob(folder + '/*.enumeration.html')
enum_base = [
os.path.split(os.path.splitext(enum)[0])[1] for enum in enum_files
]
enum_base = [enum.replace('.enumeration', '') for enum in enum_base]
enum_dict = {}
# ENUMS
for indx, enum in enumerate(enum_base):
html_file = os.path.split(enum_files[indx])[1]
base = enum.split('.')[-1]
new = '(<a class="reference internal" href="%s" title="%s"><em>%s</em></a>)' % (
html_file, base, base)
enum_dict['(<em>%s</em>)' % enum] = new
for filename in fileNames:
if "genindex" in filename or "modindex" in filename:
continue
methods_done = properties_done = False
with textfile_open(filename, "rt") as fid:
orig_text = text = fid.read()
text = text.replace('Overloaded Implementations:',
'<strong>Overloaded Implementations:</strong>')
for item in HTML_REPLACE:
if item != 'class':
text = text.replace('<dl class="%s">' % item,
'\n<br><hr />\n<dl class="%s">' % item)
newtext = ''
splitted_text = text.splitlines()
len_split = len(splitted_text)
for index, line in enumerate(splitted_text):
if index < len_split - 1:
if '– <p>' in line and '</p>' in line:
line = line.replace('– <p>', '– ')
line = line.replace('</p>', '')
if line.strip() == '<br><hr />' or line.strip(
) == '<dd><br><hr />':
next_line = splitted_text[index + 1]
stripline = next_line.strip()
# replace the <hr> with a new headline for the first method or first property
if (stripline == '<dl class="staticmethod">' or stripline == '<dl class="method">' \
or stripline == '<dl class="classmethod">') and not methods_done:
line = '\n<br><h3>Methods<a class="headerlink" href="#methods" title="Permalink to this headline">¶</a></h3>\n'
methods_done = True
elif stripline == '<dl class="attribute">' and not properties_done:
line = '\n<br><h3>Properties<a class="headerlink" href="#properties" title="Permalink to this headline">¶</a></h3>\n'
properties_done = True
newtext += line + '\n'
for old, new in list(enum_dict.items()):
newtext = newtext.replace(old, new)
newtext = addJavaScript(newtext)
basename = os.path.split(filename)[1]
if basename == 'index.html':
newtext = changeWelcomeText(newtext, options)
else:
newtext = removeHeaderImage(newtext, options)
if '1moduleindex' in basename:
newtext = tweakModuleIndex(newtext)
if orig_text != newtext:
with textfile_open(filename, "wt") as fid:
fid.write(newtext)
def postProcess(folder, options):
fileNames = glob.glob(folder + "/*.html")
enum_files = glob.glob(folder + '/*.enumeration.html')
enum_base = [
os.path.split(os.path.splitext(enum)[0])[1] for enum in enum_files
]
enum_base = [enum.replace('.enumeration', '') for enum in enum_base]
enum_dict = {}
# ENUMS
for indx, enum in enumerate(enum_base):
html_file = os.path.split(enum_files[indx])[1]
base = enum.split('.')[-1]
new = '(<a class="reference internal" href="%s" title="%s"><em>%s</em></a>)' % (
html_file, base, base)
enum_dict['(<em>%s</em>)' % enum] = new
for files in fileNames:
if "genindex" in files or "modindex" in files:
continue
methods_done = properties_done = False
fid = textfile_open(files, "rt")
orig_text = text = fid.read()
fid.close()
split = os.path.split(files)[1]
if split == 'index.html':
text = changeWelcomeText(text, options)
else:
text = text.replace('class="headerimage"',
'class="headerimage-noshow"')
text = text.replace('– <p>', '– ')
text = text.replace('<p><img alt="overload"',
'<br><p><img alt="overload"')
text = text.replace(
'<strong>Overloaded Implementations</strong>',
'<em><strong>Overloaded Implementations</strong></em>')
text = text.replace(
'<strong>~~~</strong></p>',
'<hr style="color:#0000FF;background-color:#0000FF;height:1px;border:none;width:50%;float:left" /></p><br>'
)
text = text.replace('<p><img alt="contributed"',
'<br><p><img alt="contributed"')
for item in HTML_REPLACE:
text = text.replace('<dl class="%s">' % item,
'<br><hr />\n<dl class="%s">' % item)
newtext = ''
splitted_text = text.splitlines()
len_split = len(splitted_text)
for index, line in enumerate(splitted_text):
if '<div class="admonition-availability admonition' in line:
line = '<div class="admonition-availability admonition availability">'
if index < len_split - 1:
if line.strip() == '<br><hr />' or line.strip(
) == '<dd><br><hr />':
next_line = splitted_text[index + 1]
stripline = next_line.strip()
if (stripline == '<dl class="staticmethod">' or stripline == '<dl class="method">' \
or stripline == '<dl class="classmethod">') and not methods_done:
line = '<br><h3>Methods<a class="headerlink" href="#methods" title="Permalink to this headline">¶</a></h3>' + '\n' + line
methods_done = True
elif stripline == '<dl class="attribute">' and not properties_done:
line = '<br><h3>Properties<a class="headerlink" href="#properties" title="Permalink to this headline">¶</a></h3>' + '\n' + line
properties_done = True
if '<em> ' in line and '–' in line:
line = line.replace('<em> ', '<em>')
newtext += line + '\n'
for old, new in list(enum_dict.items()):
newtext = newtext.replace(old, new)
newtext = addJavaScript(newtext)
if orig_text != newtext:
fid = textfile_open(files, "wt")
fid.write(newtext)
fid.close()
