On Fri, Sep 25, 2009 at 01:28:51PM +0100, Daniel P. Berrange wrote:
The python method help docs are copied across from the C funtion comments, but in the process all line breaks and indentation was being lost. This made the resulting text and code examples completely unreadable. Both the API doc extractor and the python generator were destroying whitespace & this fixes them to preserve it exactly.
* docs/apibuild.py: Preserve all whitespace when extracting function comments. Print function comment inside a <![CDATA[ section to fully preserve all whitespace. Look for the word 'returns' to describe return values, instead of 'return' to avoid getting confused with code examples including the C 'return' statement. * python/generator.py: Preserve all whitespace when printing function help docs * src/libvirt.c: Change any return parameter indicated by 'return' to be 'returns', to avoid confusing the API extractor [...] if desc != None and desc != "": - output.write(" <info>%s</info>\n" % (escape(desc))) + output.write(" <info><![CDATA[%s]]></info>\n" % (desc))
Ah, okay you're using CDATA !
self.indexString(name, desc) for arg in args: (name, desc) = arg @@ -1760,7 +1771,7 @@ class docBuilder: try: desc = id.extra if desc != None and desc != "": - output.write(">\n <info>%s</info>\n" % (escape(desc))) + output.write(">\n <info><![CDATA[%s]]></info>\n" % (desc)) output.write(" </typedef>\n") else: output.write("/>\n") @@ -1796,7 +1807,7 @@ class docBuilder: output.write(" <cond>%s</cond>\n"% (apstr)); try: (ret, params, desc) = id.info - output.write(" <info>%s</info>\n" % (escape(desc))) + output.write(" <info><![CDATA[%s]]></info>\n" % (desc)) self.indexString(name, desc) if ret[0] != None: if ret[0] == "void": diff --git a/python/generator.py b/python/generator.py index c34cb34..178a415 100755 --- a/python/generator.py +++ b/python/generator.py @@ -44,6 +44,7 @@ if sgmlop: self.finish_starttag = target.start self.finish_endtag = target.end self.handle_data = target.data + self.handle_cdata = target.cdata
# activate parser self.parser = sgmlop.XMLParser() @@ -78,6 +79,7 @@ class SlowParser(xmllib.XMLParser): def __init__(self, target): self.unknown_starttag = target.start self.handle_data = target.data + self.handle_cdata = target.cdata self.unknown_endtag = target.end xmllib.XMLParser.__init__(self)
@@ -108,6 +110,11 @@ class docParser: print "data %s" % text self._data.append(text)
+ def cdata(self, text): + if debug: + print "data %s" % text + self._data.append(text) + def start(self, tag, attrs):
Okay makes sense, plus the large amount of return -> Returns changes ACK ! I'm still waiting to see what this gives in the HTML docs :-) Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/