def to_rst(self, ): """ Return the attribute info ousing the attrbiute sphinx markup. Examples -------- :: >>> item = AttributeItem('indent', 'int', ... ['The indent to use for the decription block.']) >>> item.to_rst() .. attribute:: indent :annotation: = int The indent to use for the description block >>> :: >>> item = AttributeItem('indent', '', ... ['The indent to use for the decription block.']) >>> item.to_rst() .. attribute:: indent The indent to use for the description block >>> .. note:: An empty line is added at the end of the list of strings so that the results can be concatenated directly and rendered properly by shpinx. """ definition = '\n'.join(add_indent(self.definition)) template = self.template.format(self.term, self.classifier, definition) return template.splitlines()
def to_rst(self, indent=4): """ Outputs field in rst as an itme in a definition list. Arguments --------- indent : int The indent to use for the decription block. Returns ------- lines : list A list of string lines of formated rst. Example ------- >>> Field('Ioannis', 'Ιωάννης', 'Is the greek guy.') >>> print Field.to_rst() Ioannis (Ιωάννης) Is the greek guy. """ lines = [] header = '{0} ({1})'.format(self.name, self.signature) lines.append(header) lines += add_indent(self.desc, indent) return lines
def to_rst(self): """ Render ArgumentItem in sphinx friendly rst using the ``:param:`` role. Example ------- :: >>> item = ArgumentItem('indent', 'int', ... ['The indent to use for the description block.', '' 'This is the second paragraph of the argument definition.']) >>> item.to_rst() :param indent: The indent to use for the description block. This is the second paragraph of the argument definition. :type indent: int .. note:: There is no new line added at the last line of the :meth:`to_rst` method. """ argument = fix_star(self.term) argument_type = self.classifier definition = '\n'.join(add_indent(self.definition)) template = self.template.format(argument, argument_type, definition) return template.splitlines()
def _refactor_notes(self, header): """Refactor the note section to use the rst ``.. note`` directive. """ paragraph = self.get_next_paragraph() lines = ['.. note::'] lines += add_indent(paragraph) return lines
def _refactor_usage(self, header): """Refactor the note section to use the rst ``.. note`` directive. """ paragraphs = self.get_section_paragraphs() lines = ['.. rubric:: {}'.format(header)] lines += ['', '::', ''] lines += add_indent(paragraphs) return lines
def _refactor_as_item_list(self, header): """ Refactor the a section to sphinx friendly item list. Arguments --------- header : str The header name that is used for the fields (i.e. ``:<header>:``). """ items = self.extract_items(item_class=ListItem) lines = [':{0}:'.format(header.lower())] if len(items) > 0: prefix = None if len(items) == 1 else '-' for item in items: lines += add_indent(item.to_rst(prefix)) else: paragraph = self.get_next_paragraph() lines += add_indent(paragraph) return lines
def _refactor_notes(self, header): """ Refactor the notes section to sphinx friendly format. Arguments --------- header : unused This parameter is ignored in this method. """ paragraph = self.get_next_paragraph() lines = ['.. note::'] lines += add_indent(paragraph) return lines
def _refactor_example(self, header): """ Refactor the example section to sphinx friendly format. Arguments --------- header : str The header name that is used for the fields (i.e. ``:<header>:``). """ paragraph = self.get_next_paragraph() lines = ['.. rubric:: {0}'.format(header), '', '::', ''] lines += add_indent(paragraph) return lines
def _refactor_example(self, header) : """ Refactor the example section to sphinx friendly format. Arguments --------- header : str The header name that is used for the fields (i.e. ``:<header>:``). """ paragraph = self.get_next_paragraph() lines = ['.. rubric:: {0}'.format(header), '', '::', ''] lines += add_indent(paragraph) return lines
def _refactor_notes(self, header): """ Refactor the notes section to sphinx friendly format. Arguments --------- header : unused This parameter is ingnored in this method. """ paragraph = self.get_next_paragraph() lines = ['.. note::'] lines += add_indent(paragraph) return lines
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 to_rst(self, **kwards): """ Outputs the Definition in sphinx friendly rst. The method renders the definition into a list of lines that follow the rst markup. The default behaviour is to render the definition as an sphinx definition item:: <term> (<classifier>) -- <definition> Subclasses will ussualy override the method to provide custom made behaviour. However the singature of the method should hold only kword arguments which have default values. The keyword arguments can be used to pass addition rendering information to subclasses. Returns ------- lines : list A list of string lines rendered in rst. Example ------- :: >>> item = DefintionItem('lines', 'list', ['A list of string lines rendered in rst.']) >>> item.to_rst() lines *(list)* -- A list of string lines rendered in rst. .. note:: An empty line is added at the end of the list of strings so that the results can be concatenated directly and rendered properly by shpinx. """ postfix = ' --' if (len(self.definition) > 0) else '' lines = [] lines += [self.term] lines += [NEW_LINE] lines += [' *({0})*{1}'.format(self.classifier, postfix)] lines += add_indent(self.definition) # definition is all ready a list lines += [NEW_LINE] return lines
def _refactor_arguments(self, header): """ Refactor the argument section to sphinx friendly format. Arguments --------- header : unused This parameter is ignored in thi method. """ items = self.extract_items(item_class=ListItem) lines = [':{0}:'.format(header.lower())] prefix = None if len(items) == 1 else '-' for item in items: lines += add_indent(item.to_rst(prefix)) return lines
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 to_rst(self, prefix=None): """ Outputs ListItem in rst using as items in an list. Arguments --------- prefix : str The prefix to use. For example if the item is part of a numbered list then ``prefix='-'``. Example ------- >>> item = ListItem('indent', 'int', ... ['The indent to use for the description block.']) >>> item.to_rst(prefix='-') - **indent** (`int`) -- The indent to use for the description block. >>> item = ListItem('indent', 'int', ... ['The indent to use for' 'the description block.']) >>> item.to_rst(prefix='-') - **indent** (`int`) -- The indent to use for the descirption block. .. note:: An empty line is added at the end of the list of strings so that the results can be concatenated directly and rendered properly by shpinx. """ indent = 0 if (prefix is None) else len(prefix) + 1 definition = '\n'.join(add_indent(self.definition, indent)) template = self.template.format(self.term, self.classifier, definition) if prefix is not None: template = prefix + ' ' + template return template.splitlines()