On Fri, Sep 25, 2009 at 03:33:41PM +0200, Daniel Veillard wrote:
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 :-)
Hmm, I didn't check that yet, but I guess it shouldn't make any difference, since the HTML will still collapse the whitespace as before - we'd need to insert real <p> breaks & use <pre> during generation of the HTML if we wanted to maintain any kind of sane formatting Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://ovirt.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|