docs: ensure new line after colon (#1691)

* docs: ensure new line after colon

* add comment

* update goldens

* add another test case

* add another test case

* remove test code

gapic/utils/lines.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import re
 import textwrap
 from typing import Iterable, Optional
 
@@ -77,6 +78,12 @@ def wrap(text: str, width: int, *, offset: Optional[int] = None, indent: int = 0
 
     # Break off the first line of the string to address non-zero offsets.
     first = text.split('\n')[0] + '\n'
+
+    # Ensure that there are 2 new lines after a colon, otherwise
+    # the sphinx docs build will fail.
+    if first.endswith(":\n"):
+        first += "\n"
+
     if len(first) > width - offset:
         # Ensure `break_on_hyphens` is set to `False` when using
         # `textwrap.wrap` to avoid breaking hyperlinks with hyphens.
@@ -95,6 +102,11 @@ def wrap(text: str, width: int, *, offset: Optional[int] = None, indent: int = 0
 
         # Save the new `first` line.
         first = f'{initial[0]}\n'
+
+    # Ensure that there are 2 new lines after a colon, otherwise
+    # the sphinx docs build will fail.
+    text = re.sub(r':\n([^\n])', r':\n\n\1', text)
+
     text = text[len(first):].strip()
     if not text:
         return first.strip()
@@ -109,7 +121,9 @@ def wrap(text: str, width: int, *, offset: Optional[int] = None, indent: int = 0
             tokens.append(token)
             token = ''
         token += line + '\n'
-        if len(line) < width * 0.75:
+
+        # Preserve line breaks for lines that are short or end with colon.
+        if len(line) < width * 0.75 or line.endswith(':'):
             tokens.append(token)
             token = ''
     if token:

tests/integration/goldens/asset/google/cloud/asset_v1/services/asset_service/async_client.py

@@ -584,6 +584,7 @@ async def sample_create_feed():
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
         """
@@ -691,6 +692,7 @@ async def sample_get_feed():
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
         """
@@ -919,6 +921,7 @@ async def sample_update_feed():
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
         """

tests/integration/goldens/asset/google/cloud/asset_v1/services/asset_service/client.py

@@ -782,6 +782,7 @@ def sample_create_feed():
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
         """
@@ -889,6 +890,7 @@ def sample_get_feed():
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
         """
@@ -1103,6 +1105,7 @@ def sample_update_feed():
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
         """

tests/integration/goldens/asset/google/cloud/asset_v1/services/asset_service/transports/rest.py

@@ -756,6 +756,7 @@ def __call__(self,
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
             """
@@ -998,6 +999,7 @@ def __call__(self,
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
             """
@@ -1385,6 +1387,7 @@ def __call__(self,
                 exported. The asset feed must be created
                 within a project, organization, or
                 folder. Supported destinations are:
+
                 Pub/Sub topics.
 
             """

tests/integration/goldens/asset/google/cloud/asset_v1/types/asset_service.py

@@ -839,6 +839,7 @@ class Feed(proto.Message):
     An asset feed filter controls what updates are exported. The
     asset feed must be created within a project, organization, or
     folder. Supported destinations are:
+
     Pub/Sub topics.
 
     Attributes:

tests/unit/utils/test_lines.py

@@ -102,11 +102,16 @@ def test_wrap_with_short_lines():
 
 
 def test_list_each_item_in_list_has_new_line():
-    s = """Type of weather:
+    input = """Type of weather:
 - Hail
 - Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain
 - Snow"""
-    assert lines.wrap(s, width=80) == s
+    expected = """Type of weather:
+
+- Hail
+- Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain
+- Snow"""
+    assert lines.wrap(input, width=80) == expected
 
 
 def test_list_items_are_indented():
@@ -126,7 +131,7 @@ def test_list_items_are_indented():
     assert lines.wrap(input, width=60) == expected
 
 
-def test_list_new_line_preserved_after_colon():
+def test_list_items_short_text_before_list_with_new_line_preserved():
     input = """Today's forecast will have different types of weather:
 
 - A mix of hail and snow, followed by rain clouds, then finally clear sky
@@ -142,20 +147,33 @@ def test_list_new_line_preserved_after_colon():
     assert lines.wrap(input, width=60, indent=16) == expected
 
 
-def test_list_items_longer_text_before_list():
+def test_list_items_long_text_before_list_with_new_line_preserved():
     input = """Weather Weather Weather Weather Weather Weather Weather
-Weather Weather Weather Weather Weather Weather Weather
-Type of weather:
+Weather Weather Weather Weather Weather Weather Type of weather:
 
 - Hail
 - Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain
 - Snow"""
     expected = """Weather Weather Weather Weather Weather Weather Weather
-Weather Weather Weather Weather Weather Weather Weather Type
-of weather:
+Weather Weather Weather Weather Weather Weather Type of
+weather:
 
 - Hail
 - Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain Rain
   Rain
 - Snow"""
     assert lines.wrap(input, width=60) == expected
+
+
+def test_new_line_added_short_text_before_list():
+    input = """Today's forecast will have different weather:
+- A mix of hail and snow, followed by rain clouds, then finally clear sky
+- Rain
+- Snow"""
+    expected = """Today's forecast will have different weather:
+
+- A mix of hail and snow, followed by rain clouds, then
+  finally clear sky
+- Rain
+- Snow"""
+    assert lines.wrap(input, width=60) == expected