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_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 _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_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