def make_implnotes_doc(root):
# Iterate through the method tree and return the documentation string
# pertaining to implementation notes for this method.
from binder_helpers import wrap_and_indent
note_str = '*implementation notes*: '
note_str += process_text(root, '', '')
return wrap_and_indent(note_str.strip(), ' ', ' ') + '\n'
def make_compliance_doc(root):
# Iterate through the method tree and return the documentation strings
# regarding the compliance required for this method.
from binder_helpers import wrap_and_indent
comp_str = '*compliance: ' + root.get(XOSID_NS + 'type') + ' -- '
for child in root:
if child.tag == (XOSID_NS + 'description'):
comp_str = comp_str + process_text(child, '', '', width=200) + '*'
return wrap_and_indent(comp_str.strip(), ' ', ' ',
width=72) + '\n'
def make_error_doc(root):
# Iterate through the method tree and return the documentation strings
# regarding the possible exceptions raised by this method.
from binder_helpers import wrap_and_indent, caps_under_to_camel
error_str = 'raise: ' + caps_under_to_camel(
root.get(XOSID_NS + 'type')) + ' - '
for child in root:
if child.tag == (XOSID_NS + 'description'):
error_str = error_str + process_text(child, '', '')
return wrap_and_indent(error_str.strip(), ' ', ' ')
def map_xosid(self, file_name):
try:
import xml.etree.cElementTree as ET
except ImportError:
import xml.etree.ElementTree as ET
tree = ET.parse(file_name)
root = tree.getroot()
package = OrderedDict()
package['name'] = ''
package['version'] = ''
package['title'] = ''
package['copyright'] = ''
package['license'] = ''
package['summary'] = ''
package['interfaces'] = []
for elem in root.iter(self._xosid_ns + 'osid'):
##
# Get version and package name information from XML header. I
# don't recall why I was doing these seperately.
full_name = (elem.get(self._xosid_ns + 'name'))
package['full_name'] = full_name
if full_name == 'osid':
package['name'] = full_name
else:
package['name'] = full_name[5:]
package['version'] = (elem.get(self._xosid_ns + 'version'))
for child in root:
##
# Load main documentation strings
if child.tag == (self._xosid_ns + 'title'):
package['title'] = wrap_and_indent(child.text,
self._indent_str)
if child.tag == (self._xosid_ns + 'copyright'):
package['copyright'] = process_text(child, self._indent_str)
if child.tag == (self._xosid_ns + 'license'):
package['license'] = process_text(child, self._indent_str)
if child.tag == (self._xosid_ns + 'description'):
package['summary'] = process_text(child, self._indent_str)
##
# For each interface fire up the interface iterator which will
# return dictionaries that get added to an interfaces list.
if child.tag == (self._xosid_ns + 'interface'):
package['interfaces'].append(interface_iterator(child))
return package
def make_return_doc(root):
# Iterate through the method tree and return the documentation strings
# regarding the method return type.
from binder_helpers import wrap_and_indent
return_str = 'return: '
for child in root:
if child.tag == (XOSID_NS + 'interfaceType'):
return_str = return_str + '(' + child.get(XOSID_NS +
'type') + ') - '
if child.tag == (XOSID_NS + 'primitiveType'):
return_str = return_str + '(' + child.get(XOSID_NS +
'type') + ') - '
if child.tag == (XOSID_NS + 'description'):
return_str = return_str + process_text(child, '', '')
return wrap_and_indent(return_str.strip(), ' ',
' ')
def make_outline(root, i_indent, s_indent=None, width=72):
# This function is used to properly process outline tagged text
from binder_helpers import wrap_and_indent
if not s_indent:
s_indent = i_indent
outline = ''
iter_str = ''
for child in root:
if child.tag == (XOSID_NS + 'element'):
iter_str = ' '.join(child.text.split())
for elem in child.iter():
if elem.tag == (XOSID_NS + 'token'):
iter_str = iter_str + ' ``' + ' '.join(
str(elem.text).split()) + '`` '
iter_str = iter_str + '' + ' '.join(
str(elem.tail).split()) + ''
iter_str = wrap_and_indent(iter_str, i_indent, s_indent)
outline = outline + iter_str + '\n'
return outline
def make_param_doc(root):
# Iterate through the method tree and return the documentation strings
# regarding method parameters.
from binder_helpers import wrap_and_indent, camel_to_under
param_str = 'arg: ' + camel_to_under(root.get(XOSID_NS + 'name'))
for child in root:
if child.tag == (XOSID_NS + 'interfaceType'):
param_str = param_str + ' (' + child.get(XOSID_NS + 'type')
if child.get(XOSID_NS + 'array') == 'true':
param_str += '[]): '
else:
param_str += '): '
if child.tag == (XOSID_NS + 'primitiveType'):
param_str = param_str + ' (' + child.get(XOSID_NS + 'type')
if child.get(XOSID_NS + 'array') == 'true':
param_str += '[]): '
else:
param_str += '): '
if child.tag == (XOSID_NS + 'description'):
param_str = param_str + process_text(child, '', '')
return wrap_and_indent(param_str.strip(), ' ',
' ') + '\n'
def parse_docstring(text,
i_indent,
s_indent=False,
make_head=False,
make_tail=False):
# Accepts a pre-formatted documentation block and splits out the first
# sentence from the remainder of the block. All formatting in the
# remaining block should be retained. If make_head or make_tail are True
# then parse_docstring will add the triple quotes in the right places.
# Otherwise its up to the calling code to insert these. If make_head is
# False the returned headline will not be indented. This too is left up
# to the calling code. parse_doc assumes that the incoming text block
# does not begin with a special format section, like a code or outline, etc.
if not s_indent:
s_indent = i_indent
tail_str = ''
head_str = ''
if text:
first_paragraph = text.split('\n' + i_indent + '\n')[0]
subsequent_paragraphs = ''
if len(text.split('\n' + i_indent + '\n', 1)) > 1:
subsequent_paragraphs = text.split('\n' + i_indent + '\n', 1)[1]
if make_head:
head_str = i_indent + '\"\"\"'
headline_str = (head_str + (first_paragraph.split('.')[0]).strip() +
'.')
headline_str = ' '.join(headline_str.split('\n' + i_indent))
if (len(first_paragraph.split('.', 1)) > 1
and first_paragraph.split('.', 1)[1].strip() != ''):
remaining_text = first_paragraph.split('.', 1)[1].strip()
next_paragraph = remaining_text.split('\n' + i_indent + '\n', 1)[0]
next_paragraph = ' '.join(next_paragraph.split())
next_paragraph = wrap_and_indent(next_paragraph, i_indent,
s_indent)
if len(remaining_text.split('\n' + i_indent + '\n', 1)) > 1:
remaining_text = next_paragraph + '\n' + remaining_text.split(
'\n' + i_indent + '\n', 1)[1]
else:
remaining_text = next_paragraph
if subsequent_paragraphs.strip() != '':
if make_tail:
tail_str = '\n\n' + i_indent + '\"\"\"'
return {
'headline':
headline_str,
'body':
remaining_text + '\n\n' + subsequent_paragraphs + tail_str
}
else:
if make_tail:
tail_str = i_indent + '\"\"\"'
return {
'headline': headline_str,
'body': remaining_text + tail_str
}
else:
if make_tail:
tail_str = '\"\"\"'
return {'headline': headline_str, 'body': tail_str}
else:
return {'headline': '', 'body': ''}
def process_text(root,
i_indent='',
s_indent=None,
make_doc_string_head=False,
make_doc_string_tail=False,
width=72):
# Send any text blocks to this function that includes text tags for things
# like copyright symbols, paragraphs breaks, headings, tokens and code blocks
# and outlines. Outlines are dispatched to make_outline which isn't afraid
# to deal with them (but it should be).
if not s_indent:
s_indent = i_indent
make_str = ''
iter_str = ' '.join(root.text.split())
for child in root:
if child.tag == (XOSID_NS + 'copyrightSymbol'):
iter_str = iter_str + ' (c) ' + ' '.join(child.tail.split()) + ' '
if child.tag == (XOSID_NS + 'pbreak'):
make_str = (make_str + wrap_and_indent(
iter_str, i_indent, s_indent, width)) + '\n' + i_indent + '\n'
iter_str = ' '.join(child.tail.split())
if child.tag == (XOSID_NS + 'heading'):
iter_str += ' '.join(str(child.text).split())
iter_str += ' '.join(str(child.tail).split())
if child.tag == (XOSID_NS + 'token'):
if is_mixed_case(str(child.text).strip()):
if len(str(child.text).split('.')) > 1:
segments = str(child.text).split('.')
segments[-1] = camel_to_under(segments[-1])
converted_text = '.'.join(segments)
elif str(child.text).strip().split(' ')[0] != 'a':
converted_text = camel_to_under(child.text.strip())
else:
converted_text = child.text
elif str(child.text).strip('. ') in OSID_ERRORS:
converted_text = caps_under_to_camel(child.text)
else:
converted_text = child.text
if converted_text is None or converted_text.strip() == '':
pass
elif converted_text.strip().endswith('.'):
converted_text = converted_text.split('.')[0]
iter_str = iter_str + ' ``' + ' '.join(
str(converted_text).split()) + '``. '
else:
iter_str = iter_str + ' ``' + ' '.join(
str(converted_text).split()) + '`` '
iter_str = iter_str + '' + ' '.join(str(child.tail).split()) + ''
if child.tag == (XOSID_NS + 'code'):
make_str = (make_str + wrap_and_indent(
iter_str, i_indent, s_indent, width)).strip() + '\n'
iter_str = reindent(child.text.strip(), i_indent + ' ')
make_str = make_str + iter_str + i_indent + '\n'
iter_str = ' '.join(child.tail.split())
if child.tag == (XOSID_NS + 'outline'):
make_str = (make_str + wrap_and_indent(
iter_str, i_indent, s_indent, width)).strip() + '\n'
iter_str = i_indent + '\n' + make_outline(child, i_indent + ' * ',
i_indent + ' ', width)
make_str += iter_str
iter_str = ' '.join(child.tail.split())
return_str = make_str + wrap_and_indent(iter_str, i_indent, s_indent,
width)
if make_doc_string_head:
return_doc = parse_docstring(return_str,
i_indent,
s_indent,
make_tail=make_doc_string_tail)
return return_doc['headstring'] + '\n\n' + return_doc['body']
else:
return return_str