def test_get_description_lines(self):
"""
Tests that get_description_lines properly dedents docstrings and strips
out values we don't want.
"""
docstring = """line one
line two
indented line three
line four
:param str c: example param
:returns: d
"""
assert get_description_lines(docstring) == [
'line one',
'',
'line two',
'',
' indented line three',
'',
'line four',
'',
]
def test_get_description_lines_trailing_newline(self):
"""It should add a trailing line if necessary."""
assert get_description_lines('foo\n:arg') == ['foo', '']
def test_get_description_lines_none(self):
"""It should just return an empty list for None."""
assert get_description_lines(None) == []
def _render_rst(self): # pragma: no cover
"""Render lines of reStructuredText for items yielded by
:meth:`~doctor.docs.base.BaseHarness.iter_annotations`.
"""
# Create a mapping of headers to annotations. We want to group
# all annotations by a header, but they could be in multiple handlers
# so we create a map of them here with the heading as the key and
# the list of associated annotations as a list. This is so we can
# sort them alphabetically to make reading the api docs easier.
heading_to_annotations_map = defaultdict(list)
for heading, route, handler, annotations in (
self.harness.iter_annotations()):
# Set the route and handler as attributes so we can retrieve them
# when we loop through them all below.
for annotation in annotations:
annotation.route = route
annotation.handler = handler
heading_to_annotations_map[heading].append(annotation)
headings = heading_to_annotations_map.keys()
headings.sort()
previous_heading = None
for heading in headings:
annotations = heading_to_annotations_map.get(heading)
# Sort all the annotations by title.
annotations.sort(key=lambda a: a.title)
# Only emit a new heading if the resource has changed. This
# esnures that documented endpoints for the same resource all
# end up under a single heading.
if previous_heading != heading:
previous_heading = heading
yield HEADING_TOKEN + heading
for annotation in annotations:
route = annotation.route
normalized_route = normalize_route(route)
handler = annotation.handler
# Adds a title for the endpoint.
if annotation.title is not None:
yield annotation.title
yield '#' * len(annotation.title)
docstring = get_description_lines(
getattr(annotation.logic, '__doc__', None))
if annotation.request_schema:
field = '<json'
if annotation.http_method in ('DELETE', 'GET'):
field = 'query'
docstring.extend(
get_json_schema_lines(annotation,
annotation.request_schema,
field=field,
route=normalized_route,
request=True))
# Document any request headers.
defined_headers = self.harness._get_headers(
str(route), annotation).keys()
defined_headers.sort()
for header in defined_headers:
definition = self.harness.header_definitions.get(
header, '')
docstring.append(':reqheader {}: {}'.format(
header, definition))
if annotation.response_schema:
docstring.extend(
get_json_schema_lines(annotation,
annotation.response_schema,
field='>json',
route=normalized_route))
docstring.extend(self._make_example(route, handler,
annotation))
for line in http_directive(annotation.http_method,
normalized_route, docstring):
yield line
def test_get_description_lines_none(self):
"""It should just return an empty list for None."""
self.assertEqual(get_description_lines(None), [])