Dear All,Attached is the documentation for the random module in ODT format. The file includes paragraph, character, and list styles for Python objects. Also attached is a script for playing with this ODT documentation.
Here are my conclusions from this brief foray:
- Once we had a stylesheet, ODT would make it *much* easier to write
documentation: everyone knows how to use a word processor.
- However, the stylesheet itself is almost too easy to change. Any
tools would depend on it for their API, so it needs to be stable.
- OOo is not super-flexible when it comes to styles. I don't see that
you can nest paragraph-level styles, e.g.
- The way that OOo stores information is not the easiest to work with:
e.g.:
<func>foo([</func><param>foo</param><func>])</func>
rather than:
<func>foo([<param>foo</param>])</func>
Bottom line: this is a hacked-up, watered-down, non-robust version of an
XML solution. Too easy for authors, and too hard for tool-smiths. I'd
say it might be an improvement over the status quo, but not enough of
one to warrant switching.
chad
#!/usr/bin/env python
"""Sandbox for playing with ODT files as Python doc.
"""
from zipfile import ZipFile
from xml.dom import minidom
class Function:
"""Represent the documentation for a function.
"""
def __init__(self, name, params=None, description=''):
self.name = name
def __repr__(self):
return '<doc for %s>' % self.name
__str__ = __repr__
Method = Function
Class = Method
class Module:
"""Represent the documentation for a module.
"""
def __init__(self, path):
"""Path points to an ODF file; we want the content as an xml.Document.
"""
odt = ZipFile(open(path))
odt.testzip() # I believe this fails on Windows, not sure why.
content = odt.read('content.xml')
self._dom = minidom.parseString(content)
def functions(self):
"""Generate functions defined in this module.
"""
for el in self._dom.getElementsByTagName('text:span'):
if el.getAttribute('text:style-name') == "Function_20_Definition":
val = el.childNodes[0].nodeValue
if isinstance(val, basestring):
funcname = val.strip('[()], ')
if funcname:
yield Function(funcname)
def classes(self):
"""Generate classes defined in this module.
"""
for el in self._dom.getElementsByTagName('text:span'):
if el.getAttribute('text:style-name') == "Class_20_Definition":
val = el.childNodes[0].nodeValue
if isinstance(val, basestring):
classname = val.strip('[()], ')[6:]
if classname:
yield Class(classname)
doc = Module('random.odt')
print
print "Classes:"
for c in doc.classes():
print ' ', c
print
print "Functions:"
for f in doc.functions():
print ' ', f
print
import code; code.interact(local=locals())
random.odt
Description: application/vnd.oasis.opendocument.text
_______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
