Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix links and code edge cases in docs generation #2896

Merged
merged 3 commits into from Mar 27, 2023
Merged

Fix links and code edge cases in docs generation #2896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4890b73
Correctly collapse whitespace for adjacent whitespace-padded elements
jonemo Mar 24, 2023
9d2a98a
bring back lstrip() for link text
jonemo Mar 24, 2023
2ffe66e
Remove special treatment of trailing whitespace
jonemo Mar 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
23 changes: 13 additions & 10 deletions botocore/docs/bcdoc/docstringparser.py
View file
Open in desktop
Expand Up @@ -207,11 +207,19 @@ def collapse_whitespace(self):
# Collapse whitespace in situations like ``</b> <i> foo</i>`` into
# ``</b><i> foo</i>``.
for prev, cur in zip(self.children[:-1], self.children[1:]):
if prev.endswith_whitespace() and cur.startswith_whitespace():
if (
isinstance(prev, DataNode)
and prev.endswith_whitespace()
and cur.startswith_whitespace()
):
cur.lstrip()
# Same logic, but for situations like ``<b>bar </b> <i>``:
for cur, nxt in zip(self.children[:-1], self.children[1:]):
if cur.endswith_whitespace() and nxt.startswith_whitespace():
if (
isinstance(nxt, DataNode)
and cur.endswith_whitespace()
and nxt.startswith_whitespace()
):
cur.rstrip()
# Recurse into children
for child in self.children:
Expand Down Expand Up @@ -288,15 +296,10 @@ def lstrip(self):
self.rstrip()

def rstrip(self):
# If there is no content, consolidate all white-space on the right.
if self._stripped_data == '' and self._leading_whitespace != '':
self._trailing_whitespace = (
f"{self._leading_whitespace}{self._trailing_whitespace}"
)
self._leading_whitespace = ''
# Up to one trailing space is always preserved
if self._trailing_whitespace != '':
self._trailing_whitespace = ' '
self._trailing_whitespace = ''
elif self._stripped_data == '':
self.lstrip()

def collapse_whitespace(self):
"""Noop, ``DataNode.write`` always collapses whitespace"""
Expand Down
4 changes: 3 additions & 1 deletion botocore/docs/bcdoc/style.py
View file
Open in desktop
Expand Up @@ -252,8 +252,10 @@ def _clean_link_text(self):
last_write = doc.pop_write()
while not last_write.startswith('`'):
last_write = doc.pop_write() + last_write

if last_write != '':
# Remove whitespace from the start of link text.
if last_write.startswith('` '):
last_write = f'`{last_write[1:].lstrip(" ")}'
doc.push_write(last_write)

def end_a(self, next_child=None):
Expand Down
65 changes: 43 additions & 22 deletions tests/unit/docs/bcdoc/test_docstringparser.py
View file
Open in desktop
Expand Up @@ -45,7 +45,7 @@ def assert_contains_exact_lines_in_order(self, actual, expected):
def test_tag_with_collapsible_spaces(self):
html = "<p> a bcd efg </p>"
result = self.parse(html)
self.assert_contains_exact_lines_in_order(result, [b'a bcd efg '])
self.assert_contains_exact_lines_in_order(result, [b'a bcd efg'])

def test_nested_lists(self):
html = "<ul><li>Wello</li><ul><li>Horld</li></ul></ul>"
Expand Down Expand Up @@ -248,19 +248,14 @@ def test_write_empty_string(self):
@pytest.mark.parametrize(
'data, lstrip, rstrip, both',
[
# Note for cases with trailing white-space: If any white-space exists
# at the end of the string, stripping will leave behind a single space.
('foo', 'foo', 'foo', 'foo'),
(' foo', 'foo', ' foo', 'foo'),
(' foo', 'foo', ' foo', 'foo'),
('\tfoo', 'foo', '\tfoo', 'foo'),
('\t \t foo', 'foo', '\t \t foo', 'foo'),
('foo ', 'foo ', 'foo ', 'foo '),
('foo ', 'foo ', 'foo ', 'foo '),
('foo\t\t', 'foo\t\t', 'foo ', 'foo '),
(' ', ' ', ' ', ' '),
(' ', ' ', ' ', ' '),
('\t', ' ', ' ', ' '),
('foo ', 'foo ', 'foo', 'foo'),
('foo ', 'foo ', 'foo', 'foo'),
('foo\t\t', 'foo\t\t', 'foo', 'foo'),
],
)
def test_datanode_stripping(data, lstrip, rstrip, both):
Expand All @@ -287,28 +282,54 @@ def test_datanode_stripping(data, lstrip, rstrip, both):
doc.handle_data.assert_called_once_with(both)


@pytest.mark.parametrize(
'data',
[
(' '),
(' '),
('\t'),
('\t \t '),
],
)
def test_datanode_stripping_empty_string(data):
doc = mock.Mock()
doc.style = mock.Mock()
doc.translate_words.side_effect = lambda words: words
node = parser.DataNode(data)
node.lstrip()
node.write(doc)
doc.handle_data.assert_not_called()


@pytest.mark.parametrize(
'html, expected_lines',
[
('<p> foo</p>', [b'foo']),
('<p>\tfoo</p>', [b'foo']),
('<p> <span> </span> <span> <span> foo</span></span></p>', [b'foo']),
# if there are trailing white-spaces, right-stripping text always
# leaves one space character behind
('<p>foo </p>', [b'foo ']),
('<p>foo\t</p>', [b'foo ']),
('<p> foo </p>', [b'foo ']),
('<p> <span>foo </span> </p>', [b'foo ']),
# ... but right-stripping tag-nodes does not
('<p>foo </p>', [b'foo']),
('<p>foo\t</p>', [b'foo']),
('<p> foo </p>', [b'foo']),
('<p> <span>foo</span> </p>', [b'foo']),
('<p> <span>foo </span> </p>', [b'foo']),
('<p> <span> foo</span> </p>', [b'foo']),
('<p> <span> foo </span> </p>', [b'foo ']),
('<p> <span> foo </span> </p>', [b'foo']),
# various nested markup examples
('<i>italic</i>', [b'*italic*']),
('<p><i>italic</i></p>', [b'*italic*']),
('<p><i>italic</i> </p>', [b'*italic*']),
('<p><i>italic </i></p>', [b'*italic *']),
('<p><i>italic </i></p>', [b'*italic*']),
('<p>foo <i> italic </i> bar</p>', [b'foo *italic* bar']),
('<p> <span> foo <i> bar</i> </span> </p>', [b'foo *bar*']),
('<p> <span> foo<i> bar</i> </span> </p>', [b'foo* bar*']),
('<p> <span> foo <i>bar</i> </span> </p>', [b'foo *bar*']),
# links
('<a href="url">foo</a> <i>bar</i>', [b'`foo <url>`__ *bar*']),
# ReST does not support link text starting with whitespace
('<p>abc<a href="url"> foo</a></p>', [b'abc `foo <url>`__']),
('<p>abc<a href="url"> foo </a> bar</p>', [b'abc `foo <url>`__ bar']),
# code-in-a removed and whitespace removed
('<a href="url"> <code>foo</code> </a> bar', [b'`foo <url>`__ bar']),
# list items
('<li> foo</li>', [b'* foo']),
('<li> <foo> </foo><foo> foo</foo></li>', [b'* foo']),
Expand All @@ -317,16 +338,16 @@ def test_datanode_stripping(data, lstrip, rstrip, both):
('<li><foo> </foo><foo> foo</foo> <foo> bar</li>', [b'* foo bar']),
('<li><foo> </foo><foo> foo</foo><foo> bar</li>', [b'* foo bar']),
# multiple block tags in sequence are each left and right stripped
('<p> foo</p><p> bar\t</p>', [b'foo', b'bar ']),
('<p> foo</p><li> bar </li>', [b'foo', b'* bar ']),
('<p> foo</p><p> bar\t</p>', [b'foo', b'bar']),
('<p> foo</p><li> bar </li>', [b'foo', b'* bar']),
# nested block tags also work
(
'<p> <p> foo </p> <p> <span> bar </span> </p> </p>',
[b'foo ', b'bar '],
[b'foo', b'bar'],
),
],
)
def test_whitespace_collapsing_foo(html, expected_lines):
def test_whitespace_collapsing(html, expected_lines):
docstring_parser = parser.DocStringParser(ReSTDocument())
docstring_parser.feed(html)
docstring_parser.close()
Expand Down