def get_next_block(self):
""" Get the next item block from the docstring.
The method reads the next item block in the docstring. The first line
is assumed to be the DefinitionItem header and the following lines to
belong to the definition::
<header line>
<definition>
The end of the field is designated by a line with the same indent
as the field header or two empty lines are found in sequence.
"""
item_header = self.pop()
sub_indent = get_indent(item_header) + ' '
block = [item_header]
while not self.eod:
peek_0 = self.peek()
peek_1 = self.peek(1)
if is_empty(peek_0) and not peek_1.startswith(sub_indent) \
or not is_empty(peek_0) \
and not peek_0.startswith(sub_indent):
break
else:
line = self.pop()
block += [line.rstrip()]
return block
def _refactor_arguments(self, header):
"""Refactor the argument section to sphinx friendly format
"""
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
fields = self.extract_fields(indent, field_type=ArgumentField)
lines = []
for field in fields:
lines += field.to_rst(len(indent))
self.insert_lines(lines, index)
self.index += len(lines)
return
def _refactor_raises(self, header):
"""Refactor the raises section to sphinx friendly format"""
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
fields = self.extract_fields(indent, field_type=ListItemField)
lines = [indent + ':raises:']
prefix = '' if len(fields) == 1 else '- '
for field in fields:
lines += field.to_rst(len(indent) + 4, prefix)
self.insert_lines(lines, index)
self.index += len(lines)
return
def _refactor_arguments(self, header):
"""Refactor the argument section to sphinx friendly format
"""
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
fields = self.extract_fields(indent, field_type=ArgumentField)
lines = []
for field in fields:
lines += field.to_rst(len(indent))
self.insert_lines(lines, index)
self.index += len(lines)
return
def _refactor_raises(self, header):
"""Refactor the raises section to sphinx friendly format"""
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
fields = self.extract_fields(indent, field_type=ListItemField)
lines = [indent + ':raises:']
prefix = '' if len(fields) == 1 else '- '
for field in fields:
lines += field.to_rst(len(indent) + 4, prefix)
self.insert_lines(lines, index)
self.index += len(lines)
return
def _refactor_notes(self, header):
"""Refactor the note section to use the rst ``.. note`` directive.
"""
descriptions = []
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
paragraph = self.get_next_paragraph()
descriptions.append(indent + '.. note::')
descriptions += add_indent(paragraph)
self.insert_lines(descriptions, index)
self.index += len(descriptions)
return descriptions
def _refactor_notes(self, header):
"""Refactor the note section to use the rst ``.. note`` directive.
"""
descriptions = []
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
paragraph = self.get_next_paragraph()
descriptions.append(indent + '.. note::')
descriptions += add_indent(paragraph)
self.insert_lines(descriptions, index)
self.index += len(descriptions)
return descriptions
def get_next_block(self):
""" Get the next field block from the docstring.
The method reads the next block in the docstring. The first line
assumed to be the field header and the following lines to belong to
the description::
<header line>
<descrition>
The end of the field is designated by a line with the same indent
as the field header or two empty lines are found in sequence. Thus,
there are two valid field layouts:
1. No lines between fields::
<field1>
<description1>
<fieldd2>
<description2>
2. One line between fields::
<field1>
<description1>
<field2>
<description2>
"""
start = self.index
field_header = self.read()
indent = get_indent(field_header) + ' '
field = [field_header]
while (not self.eol):
peek_0 = self.peek()
peek_1 = self.peek(1)
if (is_empty(peek_0) and (not peek_1.startswith(indent))) \
or \
((not is_empty(peek_0)) and (not peek_0.startswith(indent))):
break
else:
line = self.read()
field.append(line.rstrip())
self.remove_lines(start, len(field))
self.index = start
return field
def get_next_block(self):
""" Get the next field block from the docstring.
The method reads the next block in the docstring. The first line
assumed to be the field header and the following lines to belong to
the description::
<header line>
<descrition>
The end of the field is designated by a line with the same indent
as the field header or two empty lines are found in sequence. Thus,
there are two valid field layouts:
1. No lines between fields::
<field1>
<description1>
<fieldd2>
<description2>
2. One line between fields::
<field1>
<description1>
<field2>
<description2>
"""
start = self.index
field_header = self.read()
indent = get_indent(field_header) + ' '
field = [field_header]
while (not self.eol):
peek_0 = self.peek()
peek_1 = self.peek(1)
if (is_empty(peek_0) and (not peek_1.startswith(indent))) \
or \
((not is_empty(peek_0)) and (not peek_0.startswith(indent))):
break
else:
line = self.read()
field.append(line.rstrip())
self.remove_lines(start, len(field))
self.index = start
return field
def _refactor_attributes(self, header):
"""Refactor the attributes section to sphinx friendly format"""
if self.verbose:
print '{0} Section'.format(header)
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
fields = self.extract_fields(indent, AttributeField)
header = fix_backspace(header)
lines = [indent + ':{0}:'.format(header), '']
for field in fields:
lines += field.to_rst(len(indent) + 4)
self.insert_lines(lines[:-1], index)
self.index += len(lines)
return
def _refactor_attributes(self, header):
"""Refactor the attributes section to sphinx friendly format"""
if self.verbose:
print '{0} Section'.format(header)
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
fields = self.extract_fields(indent, AttributeField)
descriptions = []
for field in fields:
descriptions += field.to_rst(len(indent))
self.insert_lines(descriptions[:-1], index)
self.index += len(descriptions)
return
def _refactor_notes(self, header):
"""Refactor the argument section to sphinx friendly format.
"""
if self.verbose:
print 'Refactoring Notes'
descriptions = []
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
paragraph = self.get_next_paragraph()
descriptions.append(indent + '.. note::')
descriptions += add_indent(paragraph)
self.insert_lines(descriptions, index)
self.index += len(descriptions)
return descriptions
def _refactor_attributes(self, header):
"""Refactor the attributes section to sphinx friendly format"""
if self.verbose:
print '{0} Section'.format(header)
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
fields = self.extract_fields(indent, AttributeField)
descriptions = []
for field in fields:
descriptions += field.to_rst(len(indent))
self.insert_lines(descriptions[:-1], index)
self.index += len(descriptions)
return
def _refactor_notes(self, header):
"""Refactor the argument section to sphinx friendly format.
"""
if self.verbose:
print 'Refactoring Notes'
descriptions = []
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
paragraph = self.get_next_paragraph()
descriptions.append(indent + '.. note::')
descriptions += add_indent(paragraph)
self.insert_lines(descriptions, index)
self.index += len(descriptions)
return descriptions
def _refactor_attributes(self, header):
"""Refactor the attributes section to sphinx friendly format"""
if self.verbose:
print '{0} Section'.format(header)
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
fields = self.extract_fields(indent, AttributeField)
header = fix_backspace(header)
lines = [indent + ':{0}:'.format(header), '']
for field in fields:
lines += field.to_rst(len(indent) + 4)
self.insert_lines(lines[:-1], index)
self.index += len(lines)
return
def _refactor_methods(self, header):
"""Refactor the methods section to sphinx friendly format.
"""
if self.verbose:
print '{0} section'.format(header)
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
method_fields = self.extract_fields(indent, MethodField)
lines = []
if len(method_fields) > 0 :
name_length = max_name_length(method_fields)
method_length = max_header_length(method_fields)
desc_length = max_desc_length(method_fields)
first_column = len(indent)
second_column = first_column + method_length + name_length + 13
first_column_str = '=' * (method_length + name_length + 12)
second_column_str = '=' * desc_length
border = '{0}{1} {2}'.format(indent,
first_column_str,
second_column_str)
length = len(border)
empty = length * ' '
headings = empty[:]
headings = replace_at('Methods', headings, first_column)
headings = replace_at('Description', headings, second_column)
lines.append(border)
lines.append(headings)
lines.append(border)
for field in method_fields:
lines += field.to_rst(length, first_column, second_column)
lines.append(border)
lines = [line.rstrip() for line in lines]
self.insert_lines(lines, index)
self.index += len(lines)
return
def _refactor_methods(self, header):
"""Refactor the methods section to sphinx friendly format.
"""
if self.verbose:
print '{0} section'.format(header)
index = self.index
self.remove_lines(index, 2)
indent = get_indent(self.peek())
method_fields = self.extract_fields(indent, MethodField)
lines = []
if len(method_fields) > 0:
name_length = max_name_length(method_fields)
method_length = max_header_length(method_fields)
desc_length = max_desc_length(method_fields)
first_column = len(indent)
second_column = first_column + method_length + name_length + 13
first_column_str = '=' * (method_length + name_length + 12)
second_column_str = '=' * desc_length
border = '{0}{1} {2}'.format(indent, first_column_str,
second_column_str)
length = len(border)
empty = length * ' '
headings = empty[:]
headings = replace_at('Methods', headings, first_column)
headings = replace_at('Description', headings, second_column)
lines.append(border)
lines.append(headings)
lines.append(border)
for field in method_fields:
lines += field.to_rst(length, first_column, second_column)
lines.append(border)
lines = [line.rstrip() for line in lines]
self.insert_lines(lines, index)
self.index += len(lines)
return
def _refactor_header(self, header):
""" Refactor the header section using the rubric directive.
The method has been tested and supports refactoring single word
headers, two word headers and headers that include a backslash
''\''.
Arguments
---------
header : string
The header string to use with the rubric directive.
"""
index = self.index
indent = get_indent(self.peek())
self.remove_lines(index, 2)
descriptions = []
header = fix_backspace(header)
descriptions += [indent + '.. rubric:: {0}'.format(header), '']
self.insert_lines(descriptions, index)
self.index += len(descriptions)
return descriptions
def _refactor_header(self, header):
""" Refactor the header section using the rubric directive.
The method has been tested and supports refactoring single word
headers, two word headers and headers that include a backslash
''\''.
Arguments
---------
header : string
The header string to use with the rubric directive.
"""
index = self.index
indent = get_indent(self.peek())
self.remove_lines(index, 2)
descriptions = []
header = fix_backspace(header)
descriptions += [indent + '.. rubric:: {0}'.format(header), '']
self.insert_lines(descriptions, index)
self.index += len(descriptions)
return descriptions
