lib/libxml2
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libxml2.git synced 2025-10-24 13:33:01 +03:00
Code Activity

Port doc/examples/index.py to Python 3

Browse Source 
- Make sure that examples.xml is generated deterministically
- Sort includes by line number
This commit is contained in:
Nick Wellnhofer
2022-08-18 21:03:56 +02:00
parent 5264fa1100
commit 18d79460ab
2 changed files with 112 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/examples/examples.xsl
View File

@@ -37,6 +37,7 @@
<p>Includes:</p> <p>Includes:</p>
<ul> <ul>
<xsl:for-each select="includes/include"> <xsl:for-each select="includes/include">
<xsl:sort select="@line" data-type="number"/>
<xsl:apply-templates select='.'/> <xsl:apply-templates select='.'/>
</xsl:for-each> </xsl:for-each>
</ul> </ul>

239
doc/examples/index.py
View File

@@ -2,12 +2,12 @@
# #
# Indexes the examples and build an XML description # Indexes the examples and build an XML description
# #
import string
import glob import glob
import sys import sys
try: try:
import libxml2 import libxml2
except: except:
print("libxml2 python bindings not available")
sys.exit(1) sys.exit(1)
sys.path.insert(0, "..") sys.path.insert(0, "..")
from apibuild import CParser, escape from apibuild import CParser, escape
@@ -28,11 +28,11 @@ def load_api():
return return
api_dict = {} api_dict = {}
try: try:
print "loading ../libxml2-api.xml" print("loading ../libxml2-api.xml")
api_doc = libxml2.parseFile("../libxml2-api.xml") api_doc = libxml2.parseFile("../libxml2-api.xml")
except: except:
print "failed to parse ../libxml2-api.xml" print("failed to parse ../libxml2-api.xml")
sys.exit(1) sys.exit(1)
def find_symbol(name): def find_symbol(name):
global api_dict global api_dict
@@ -43,50 +43,50 @@ def find_symbol(name):
if name == None: if name == None:
return return
if api_dict.has_key(name): if name in api_dict:
return api_dict[name] return api_dict[name]
ctxt = api_doc.xpathNewContext() ctxt = api_doc.xpathNewContext()
res = ctxt.xpathEval("/api/symbols/*[@name = '%s']" % (name)) res = ctxt.xpathEval("/api/symbols/*[@name = '%s']" % (name))
if type(res) == type([]) and len(res) >= 1: if type(res) == type([]) and len(res) >= 1:
if len(res) > 1: if len(res) > 1:
print "Found %d references to %s in the API" % (len(res), name) print("Found %d references to %s in the API" % (len(res), name))
node = res[0] node = res[0]
typ = node.name typ = node.name
file = node.xpathEval("string(@file)") file = node.xpathEval("string(@file)")
info = node.xpathEval("string(info)") info = node.xpathEval("string(info)")
else: else:
print "Reference %s not found in the API" % (name) print("Reference %s not found in the API" % (name))
return None return None
ret = (typ, file, info) ret = (typ, file, info)
api_dict[name] = ret api_dict[name] = ret
return ret return ret
def parse_top_comment(filename, comment): def parse_top_comment(filename, comment):
res = {} res = {}
lines = string.split(comment, "\n") lines = comment.split("\n")
item = None item = None
for line in lines: for line in lines:
while line != "" and (line[0] == ' ' or line[0] == '\t'): while line != "" and (line[0] == ' ' or line[0] == '\t'):
line = line[1:] line = line[1:]
while line != "" and line[0] == '*': while line != "" and line[0] == '*':
line = line[1:] line = line[1:]
while line != "" and (line[0] == ' ' or line[0] == '\t'): while line != "" and (line[0] == ' ' or line[0] == '\t'):
line = line[1:] line = line[1:]
try: try:
(it, line) = string.split(line, ":", 1) (it, line) = line.split(":", 1)
item = it item = it
while line != "" and (line[0] == ' ' or line[0] == '\t'): while line != "" and (line[0] == ' ' or line[0] == '\t'):
line = line[1:] line = line[1:]
if res.has_key(item): if item in res:
res[item] = res[item] + " " + line res[item] = res[item] + " " + line
else: else:
res[item] = line res[item] = line
except: except:
if item != None: if item != None:
if res.has_key(item): if item in res:
res[item] = res[item] + " " + line res[item] = res[item] + " " + line
else: else:
res[item] = line res[item] = line
return res return res
def parse(filename, output): def parse(filename, output):
@@ -100,83 +100,86 @@ def parse(filename, output):
output.write(" <example filename='%s'>\n" % filename) output.write(" <example filename='%s'>\n" % filename)
try: try:
synopsis = info['synopsis'] synopsis = info['synopsis']
output.write(" <synopsis>%s</synopsis>\n" % escape(synopsis)); output.write(" <synopsis>%s</synopsis>\n" % escape(synopsis));
except: except:
print "Example %s lacks a synopsis description" % (filename) print("Example %s lacks a synopsis description" % (filename))
try: try:
purpose = info['purpose'] purpose = info['purpose']
output.write(" <purpose>%s</purpose>\n" % escape(purpose)); output.write(" <purpose>%s</purpose>\n" % escape(purpose));
except: except:
print "Example %s lacks a purpose description" % (filename) print("Example %s lacks a purpose description" % (filename))
try: try:
usage = info['usage'] usage = info['usage']
output.write(" <usage>%s</usage>\n" % escape(usage)); output.write(" <usage>%s</usage>\n" % escape(usage));
except: except:
print "Example %s lacks an usage description" % (filename) print("Example %s lacks an usage description" % (filename))
try: try:
test = info['test'] test = info['test']
output.write(" <test>%s</test>\n" % escape(test)); output.write(" <test>%s</test>\n" % escape(test));
progname=filename[0:-2] progname=filename[0:-2]
command=string.replace(test, progname, './' + progname, 1) command=test.replace(progname, './' + progname, 1)
tests.append(command) tests.append(command)
except: except:
pass pass
try: try:
author = info['author'] author = info['author']
output.write(" <author>%s</author>\n" % escape(author)); output.write(" <author>%s</author>\n" % escape(author));
except: except:
print "Example %s lacks an author description" % (filename) print("Example %s lacks an author description" % (filename))
try: try:
copy = info['copy'] copy = info['copy']
output.write(" <copy>%s</copy>\n" % escape(copy)); output.write(" <copy>%s</copy>\n" % escape(copy));
except: except:
print "Example %s lacks a copyright description" % (filename) print("Example %s lacks a copyright description" % (filename))
try: try:
section = info['section'] section = info['section']
output.write(" <section>%s</section>\n" % escape(section)); output.write(" <section>%s</section>\n" % escape(section));
if sections.has_key(section): if section in sections:
sections[section].append(filename) sections[section].append(filename)
else: else:
sections[section] = [filename] sections[section] = [filename]
except: except:
print "Example %s lacks a section description" % (filename) print("Example %s lacks a section description" % (filename))
for topic in info.keys(): for topic in sorted(info.keys()):
if topic != "purpose" and topic != "usage" and \ if topic != "purpose" and topic != "usage" and \
topic != "author" and topic != "copy" and \ topic != "author" and topic != "copy" and \
topic != "section" and topic != "synopsis" and topic != "test": topic != "section" and topic != "synopsis" and topic != "test":
str = info[topic] str = info[topic]
output.write(" <extra topic='%s'>%s</extra>\n" % ( output.write(" <extra topic='%s'>%s</extra>\n" % (
escape(topic), escape(str))) escape(topic), escape(str)))
output.write(" <includes>\n") output.write(" <includes>\n")
for include in idx.includes.keys(): for include in sorted(idx.includes.keys()):
if include.find("libxml") != -1: if include.find("libxml") != -1:
output.write(" <include>%s</include>\n" % (escape(include))) id = idx.includes[include]
line = id.get_lineno()
output.write(" <include line='%d'>%s</include>\n" %
(line, escape(include)))
output.write(" </includes>\n") output.write(" </includes>\n")
output.write(" <uses>\n") output.write(" <uses>\n")
for ref in idx.references.keys(): for ref in sorted(idx.references.keys()):
id = idx.references[ref] id = idx.references[ref]
name = id.get_name() name = id.get_name()
line = id.get_lineno() line = id.get_lineno()
if symbols.has_key(name): if name in symbols:
sinfo = symbols[name] sinfo = symbols[name]
refs = sinfo[0] refs = sinfo[0]
# gather at most 5 references per symbols # gather at most 5 references per symbols
if refs > 5: if refs > 5:
continue continue
sinfo.append(filename) sinfo.append(filename)
sinfo[0] = refs + 1 sinfo[0] = refs + 1
else: else:
symbols[name] = [1, filename] symbols[name] = [1, filename]
info = find_symbol(name) info = find_symbol(name)
if info != None: if info != None:
type = info[0] type = info[0]
file = info[1] file = info[1]
output.write(" <%s line='%d' file='%s' name='%s'/>\n" % (type, output.write(" <%s line='%d' file='%s' name='%s'/>\n" % (type,
line, file, name)) line, file, name))
else: else:
type = id.get_type() type = id.get_type()
output.write(" <%s line='%d' name='%s'/>\n" % (type, output.write(" <%s line='%d' name='%s'/>\n" % (type,
line, name)) line, name))
output.write(" </uses>\n") output.write(" </uses>\n")
output.write(" </example>\n") output.write(" </example>\n")
@@ -187,15 +190,13 @@ def dump_symbols(output):
global symbols global symbols
output.write(" <symbols>\n") output.write(" <symbols>\n")
keys = symbols.keys() for symbol in sorted(symbols.keys()):
keys.sort()
for symbol in keys:
output.write(" <symbol name='%s'>\n" % (symbol)) output.write(" <symbol name='%s'>\n" % (symbol))
info = symbols[symbol] info = symbols[symbol]
i = 1 i = 1
while i < len(info): while i < len(info):
output.write(" <ref filename='%s'/>\n" % (info[i])) output.write(" <ref filename='%s'/>\n" % (info[i]))
i = i + 1 i = i + 1
output.write(" </symbol>\n") output.write(" </symbol>\n")
output.write(" </symbols>\n") output.write(" </symbols>\n")
@@ -203,15 +204,13 @@ def dump_sections(output):
global sections global sections
output.write(" <sections>\n") output.write(" <sections>\n")
keys = sections.keys() for section in sorted(sections.keys()):
keys.sort()
for section in keys:
output.write(" <section name='%s'>\n" % (section)) output.write(" <section name='%s'>\n" % (section))
info = sections[section] info = sections[section]
i = 0 i = 0
while i < len(info): while i < len(info):
output.write(" <example filename='%s'/>\n" % (info[i])) output.write(" <example filename='%s'/>\n" % (info[i]))
i = i + 1 i = i + 1
output.write(" </section>\n") output.write(" </section>\n")
output.write(" </sections>\n") output.write(" </sections>\n")
@@ -231,19 +230,19 @@ LDADD = $(top_builddir)/libxml2.la
CLEANFILES = *.tmp CLEANFILES = *.tmp
rebuild: rebuild:
cd $(srcdir) && $(PYTHON) index.py \tcd $(srcdir) && $(PYTHON) index.py
$(MAKE) Makefile \t$(MAKE) Makefile
cd $(srcdir) && xsltproc examples.xsl examples.xml \tcd $(srcdir) && xsltproc examples.xsl examples.xml
-cd $(srcdir) && xmllint --valid --noout index.html \t-cd $(srcdir) && xmllint --valid --noout index.html
.PHONY: rebuild .PHONY: rebuild
install-data-local: install-data-local:
$(MKDIR_P) $(DESTDIR)$(docdir)/examples \t$(MKDIR_P) $(DESTDIR)$(docdir)/examples
-$(INSTALL) -m 0644 $(srcdir)/*.html $(srcdir)/*.c $(DESTDIR)$(docdir)/examples/ \t-$(INSTALL) -m 0644 $(srcdir)/*.html $(srcdir)/*.c $(DESTDIR)$(docdir)/examples/
clean-local: clean-local:
test -f Makefile.am || rm -f test?.xml \ttest -f Makefile.am || rm -f test?.xml
""" """
examples.sort() examples.sort()
@@ -269,28 +268,12 @@ clean-local:
Makefile = Makefile + '\t@grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0\n' Makefile = Makefile + '\t@grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0\n'
Makefile = Makefile + "\t@rm *.tmp\n" Makefile = Makefile + "\t@rm *.tmp\n"
try: try:
old = open("Makefile.am", "r").read() old = open("Makefile.am", "r").read()
if old != Makefile: if old != Makefile:
n = open("Makefile.am", "w").write(Makefile) n = open("Makefile.am", "w").write(Makefile)
print "Updated Makefile.am" print("Updated Makefile.am")
except: except:
print "Failed to read or save Makefile.am" print("Failed to read or save Makefile.am")
# #
# # Autogenerate the .cvsignore too ... DEPRECATED
# #
# ignore = """.memdump
#Makefile.in
#Makefile
#"""
# for example in examples:
# ignore = ignore + "%s\n" % (example)
# try:
# old = open(".cvsignore", "r").read()
# if old != ignore:
# n = open(".cvsignore", "w").write(ignore)
# print "Updated .cvsignore"
# except:
# print "Failed to read or save .cvsignore"
if __name__ == "__main__": if __name__ == "__main__":
load_api() load_api()
@@ -298,8 +281,8 @@ if __name__ == "__main__":
output.write("<examples>\n") output.write("<examples>\n")
for file in sorted(glob.glob('*.c')): for file in sorted(glob.glob('*.c')):
parse(file, output) parse(file, output)
examples.append(file[:-2]) examples.append(file[:-2])
dump_symbols(output) dump_symbols(output)
dump_sections(output) dump_sections(output)