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