def test_write_py_doc_string(self):
style = ReSTStyle(ReSTDocument())
docstring = ('This describes a function\n'
':param foo: Describes foo\n'
'returns: None')
style.write_py_doc_string(docstring)
self.assertEqual(style.doc.getvalue(), six.b(docstring + '\n'))
def test_escape_href_link(self):
style = ReSTStyle(ReSTDocument())
style.start_a(attrs=[('href', 'http://example.org')])
style.doc.write('foo: the next bar')
style.end_a()
self.assertEqual(
style.doc.getvalue(),
six.b('`foo\\: the next bar <http://example.org>`__ '))
def test_internal_link(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'html'
style.internal_link('MyLink', '/index')
self.assertEqual(
style.doc.getvalue(),
six.b(':doc:`MyLink </index>`')
)
def test_hidden_toctree_non_html(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.hidden_toctree()
style.hidden_tocitem('foo')
style.hidden_tocitem('bar')
self.assertEqual(
style.doc.getvalue(),
six.b(''))
def test_write_py_doc_string(self):
style = ReSTStyle(ReSTDocument())
docstring = (
'This describes a function\n'
':param foo: Describes foo\n'
'returns: None'
)
style.write_py_doc_string(docstring)
self.assertEqual(style.doc.getvalue(), six.b(docstring + '\n'))
def test_href_link(self):
style = ReSTStyle(ReSTDocument())
style.start_a(attrs=[('href', 'http://example.org')])
style.doc.write('example')
style.end_a()
self.assertEqual(
style.doc.getvalue(),
six.b('`example <http://example.org>`__ ')
)
def __init__(self, target='man'):
self.style = ReSTStyle(self)
self.target = target
self.parser = DocStringParser(self)
self.keep_data = True
self.do_translation = False
self.translation_map = {}
self.hrefs = {}
self._writes = []
self._last_doc_string = None
def test_new_line(self):
style = ReSTStyle(ReSTDocument())
style.new_line()
self.assertEqual(style.doc.getvalue(), six.b('\n'))
style.do_p = False
style.new_line()
self.assertEqual(style.doc.getvalue(), six.b('\n\n'))
def __init__(self, target='man'):
self.style = ReSTStyle(self)
self.target = target
self.parser = DocStringParser(self)
self.keep_data = True
self.do_translation = False
self.translation_map = {}
self.hrefs = {}
self._writes = []
self._last_doc_string = None
def test_escape_href_link(self):
style = ReSTStyle(ReSTDocument())
style.start_a(attrs=[('href', 'http://example.org')])
style.doc.write('foo: the next bar')
style.end_a()
self.assertEqual(style.doc.getvalue(),
six.b('`foo\\: the next bar <http://example.org>`_ '))
def test_href_link(self):
style = ReSTStyle(ReSTDocument())
style.start_a(attrs=[('href', 'http://example.org')])
style.doc.write('example')
style.end_a()
self.assertEqual(style.doc.getvalue(),
six.b('`example <http://example.org>`_ '))
def test_hidden_toctree_non_html(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.hidden_toctree()
style.hidden_tocitem('foo')
style.hidden_tocitem('bar')
self.assertEqual(style.doc.getvalue(), six.b(''))
def test_examples(self):
style = ReSTStyle(ReSTDocument())
self.assertTrue(style.doc.keep_data)
style.start_examples()
self.assertFalse(style.doc.keep_data)
style.end_examples()
self.assertTrue(style.doc.keep_data)
def test_sphinx_py_method_with_params(self):
style = ReSTStyle(ReSTDocument())
style.start_sphinx_py_method('method', 'foo=None')
style.end_sphinx_py_method()
self.assertEqual(
style.doc.getvalue(),
six.b('\n\n.. py:method:: method(foo=None)\n\n \n\n'))
def test_toctree_man(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.toctree()
style.tocitem('foo')
style.tocitem('bar')
self.assertEqual(style.doc.getvalue(),
six.b('\n\n\n* foo\n\n\n* bar\n\n'))
def test_new_line(self):
style = ReSTStyle(ReSTDocument())
style.new_line()
self.assertEqual(style.doc.getvalue(), six.b('\n'))
style.do_p = False
style.new_line()
self.assertEqual(style.doc.getvalue(), six.b('\n\n'))
def test_hidden_toctree_html(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'html'
style.hidden_toctree()
style.hidden_tocitem('foo')
style.hidden_tocitem('bar')
self.assertEqual(
style.doc.getvalue(),
six.b('\n.. toctree::\n :maxdepth: 1'
'\n :hidden:\n\n foo\n bar\n'))
def test_sphinx_reference_label_html(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'html'
style.sphinx_reference_label('foo', 'bar')
self.assertEqual(style.doc.getvalue(), six.b(':ref:`bar <foo>`'))
def test_external_link(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'html'
style.external_link('MyLink', 'http://example.com/foo')
self.assertEqual(style.doc.getvalue(),
six.b('`MyLink <http://example.com/foo>`_'))
def test_sphinx_py_attr(self):
style = ReSTStyle(ReSTDocument())
style.start_sphinx_py_attr('Foo')
style.end_sphinx_py_attr()
self.assertEqual(style.doc.getvalue(),
six.b('\n\n.. py:attribute:: Foo\n\n \n\n'))
def test_non_top_level_lists_are_indented(self):
style = ReSTStyle(ReSTDocument())
# Start the top level list
style.start_ul()
# Write one list element
style.start_li()
style.doc.handle_data('foo')
style.end_li()
self.assertEqual(style.doc.getvalue(), six.b("\n\n\n* foo\n"))
# Start the nested list
style.start_ul()
# Write an element to the nested list
style.start_li()
style.doc.handle_data('bar')
style.end_li()
self.assertEqual(style.doc.getvalue(),
six.b("\n\n\n* foo\n\n\n \n * bar\n "))
def test_sphinx_py_method(self):
style = ReSTStyle(ReSTDocument())
style.start_sphinx_py_method('method')
style.end_sphinx_py_method()
self.assertEqual(style.doc.getvalue(),
six.b('\n\n.. py:method:: method\n\n \n\n'))
def test_code(self):
style = ReSTStyle(ReSTDocument())
style.code('foobar')
self.assertEqual(style.doc.getvalue(), six.b('``foobar`` '))
def test_ref(self):
style = ReSTStyle(ReSTDocument())
style.ref('foobar', 'http://foo.bar.com')
self.assertEqual(style.doc.getvalue(),
six.b(':doc:`foobar <http://foo.bar.com>`'))
def test_spaces(self):
style = ReSTStyle(None, 4)
self.assertEqual(style.spaces(), '')
style.indent()
self.assertEqual(style.spaces(), ' ')
style.indent()
self.assertEqual(style.spaces(), ' ')
style.dedent()
self.assertEqual(style.spaces(), ' ')
style.dedent()
self.assertEqual(style.spaces(), '')
style.dedent()
self.assertEqual(style.spaces(), '')
def test_italics(self):
style = ReSTStyle(ReSTDocument())
style.italics('foobar')
self.assertEqual(style.doc.getvalue(), six.b('*foobar* '))
def test_handle_no_text_hrefs(self):
style = ReSTStyle(ReSTDocument())
style.start_a(attrs=[('href', 'http://example.org')])
style.end_a()
self.assertEqual(style.doc.getvalue(),
six.b('`<http://example.org>`_ '))
def test_internal_link_in_man_page(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.internal_link('MyLink', '/index')
self.assertEqual(style.doc.getvalue(), six.b('MyLink'))
def test_empty_code(self):
style = ReSTStyle(ReSTDocument())
style.start_code()
style.end_code()
self.assertEqual(style.doc.getvalue(), six.b(''))
def test_external_link_in_man_page(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.external_link('MyLink', 'http://example.com/foo')
self.assertEqual(style.doc.getvalue(), six.b('MyLink'))
def test_codeblock(self):
style = ReSTStyle(ReSTDocument())
style.codeblock('foobar')
self.assertEqual(style.doc.getvalue(),
six.b('::\n\n foobar\n\n\n'))
def test_bold(self):
style = ReSTStyle(ReSTDocument())
style.bold('foobar')
self.assertEqual(style.doc.getvalue(), six.b('**foobar** '))
def test_sphinx_reference_label_non_html_no_text(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.sphinx_reference_label('foo')
self.assertEqual(style.doc.getvalue(), six.b('foo'))
def test_p(self):
style = ReSTStyle(ReSTDocument())
style.start_p()
style.doc.write('foo')
style.end_p()
self.assertEqual(style.doc.getvalue(), six.b('\n\nfoo\n\n'))
def test_table_of_contents(self):
style = ReSTStyle(ReSTDocument())
style.table_of_contents()
self.assertEqual(style.doc.getvalue(), six.b('.. contents:: '))
def test_h3(self):
style = ReSTStyle(ReSTDocument())
style.h3('foobar fiebaz')
self.assertEqual(
style.doc.getvalue(),
six.b('\n\n-------------\nfoobar fiebaz\n-------------\n\n'))
def test_table_of_contents_with_title_and_depth(self):
style = ReSTStyle(ReSTDocument())
style.table_of_contents(title='Foo', depth=2)
self.assertEqual(style.doc.getvalue(),
six.b('.. contents:: Foo\n :depth: 2\n'))
def test_sphinx_py_class(self):
style = ReSTStyle(ReSTDocument())
style.start_sphinx_py_class('FooClass')
style.end_sphinx_py_class()
self.assertEqual(style.doc.getvalue(),
six.b('\n\n.. py:class:: FooClass\n\n \n\n'))
class ReSTDocument(object):
def __init__(self, target='man'):
self.style = ReSTStyle(self)
self.target = target
self.parser = DocStringParser(self)
self.keep_data = True
self.do_translation = False
self.translation_map = {}
self.hrefs = {}
self._writes = []
self._last_doc_string = None
def _write(self, s):
if self.keep_data and s is not None:
self._writes.append(s)
def write(self, content):
"""
Write content into the document.
"""
self._write(content)
def writeln(self, content):
"""
Write content on a newline.
"""
self._write('%s%s\n' % (self.style.spaces(), content))
def peek_write(self):
"""
Returns the last content written to the document without
removing it from the stack.
"""
return self._writes[-1]
def pop_write(self):
"""
Removes and returns the last content written to the stack.
"""
return self._writes.pop()
def push_write(self, s):
"""
Places new content on the stack.
"""
self._writes.append(s)
def getvalue(self):
"""
Returns the current content of the document as a string.
"""
if self.hrefs:
self.style.new_paragraph()
for refname, link in self.hrefs.items():
self.style.link_target_definition(refname, link)
return ''.join(self._writes).encode('utf-8')
def translate_words(self, words):
return [self.translation_map.get(w, w) for w in words]
def handle_data(self, data):
if data and self.keep_data:
self._write(data)
def include_doc_string(self, doc_string):
if doc_string:
try:
start = len(self._writes)
self.parser.feed(doc_string)
self.parser.close()
end = len(self._writes)
self._last_doc_string = (start, end)
except Exception:
LOG.debug('Error parsing doc string', exc_info=True)
LOG.debug(doc_string)
def remove_last_doc_string(self):
# Removes all writes inserted by last doc string
if self._last_doc_string is not None:
start, end = self._last_doc_string
del self._writes[start:end]
