Merge ~lloydwaltersj/maas:oapi-line-break-op-desc into maas:master

[Jack Lloyd-Walters]

Remove ungrammatical linebreak in operation description

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-line-break-op-desc lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/364/consoleText
COMMIT: 05fd9ccfcdb9b0725509fafb755e91539b2d9c29

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-line-break-op-desc lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/365/consoleText
COMMIT: da502e5fd6f5a0e4d399ff41443161312e042dd9

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-line-break-op-desc lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 602d019fa8e0c9413ab5212df706a3a0a78b5a4e

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-line-break-op-desc lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/367/consoleText
COMMIT: 2fc42091a1a65aa326173ac8f7cf66a3eaf36030

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-line-break-op-desc lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 3b18ced2992ada2ea068ca3c84345b197ec6c6e4

review: Approve

[Adam Collard (adam-collard)]

review: Approve

[MAAS Lander (maas-lander)]

LANDING
-b oapi-line-break-op-desc lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED BUILD
LOG: http://maas-ci.internal:8080/job/maas-tester/377/consoleText

[Jack Lloyd-Walters (lloydwaltersj)]

jenkins: !test

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-line-break-op-desc lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 3b18ced2992ada2ea068ca3c84345b197ec6c6e4

review: Approve

diff --git a/src/maasserver/api/doc_oapi.py b/src/maasserver/api/doc_oapi.py
index 543c571..c579acd 100644
--- a/src/maasserver/api/doc_oapi.py
+++ b/src/maasserver/api/doc_oapi.py
@@ -9,6 +9,7 @@ This definition follows the rules and limitations of the ReST documentation.
 
 from inspect import getdoc
 import json
+import re
 from textwrap import dedent
 
 from django.http import HttpResponse
@@ -135,13 +136,21 @@ def _new_path_item(params):
     return path_item
 
 
+def _prettify(doc):
+    """Cleans up text by replacing newlines with spaces, so that sentences are
+    not broken apart prematurely.
+    Respects paragraphing by not replacing newlines that occur after periods.
+    """
+    return re.sub("(?<![.\n])[\n]+", " ", dedent(doc)).strip()
+
+
 def _render_oapi_oper_item(http_method, op, doc, uri_params, function):
     oper_id = op or support.OperationsResource.crudmap.get(http_method)
     oper_obj = {
         "operationId": f"{doc.name}_{oper_id}",
         "tags": [doc.handler.api_doc_section_name],
         "summary": f"{doc.name} {oper_id}",
-        "description": dedent(doc.doc).strip(),
+        "description": _prettify(doc.doc),
         "responses": {},
     }
     oper_docstring = _oapi_item_from_docstring(
@@ -192,9 +201,9 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
         ap.parse(docstring)
         ap_dict = ap.get_dict()
         oper_obj["summary"] = ap_dict["description_title"].strip()
-        oper_obj["description"] = ap_dict["description"].strip()
+        oper_obj["description"] = _prettify(ap_dict["description"])
         for param in ap_dict["params"]:
-            description = param["description_stripped"]
+            description = _prettify(param["description_stripped"])
             name = param["name"].strip("}{")
             required = param["options"]["required"].lower() == "true"
             if param["name"][0] == "{":
@@ -222,8 +231,10 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
 
         for (status, content) in _response_pair(ap_dict):
             response = {
-                "description": content.get(
-                    "description_stripped", status["description_stripped"]
+                "description": _prettify(
+                    content.get(
+                        "description_stripped", status["description_stripped"]
+                    )
                 ),
             }
             match content.get("type", "").lower():
@@ -254,7 +265,7 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
 
             status_code = status["name"]
             if not status_code.isdigit():
-                status_code = status["description_stripped"]
+                status_code = _prettify(status["description_stripped"])
             oper_obj.setdefault("responses", {}).update(
                 {status_code: response},
             )
diff --git a/src/maasserver/api/tests/test_oapi.py b/src/maasserver/api/tests/test_oapi.py
index 0e27da9..d22c2cc 100644
--- a/src/maasserver/api/tests/test_oapi.py
+++ b/src/maasserver/api/tests/test_oapi.py
@@ -5,7 +5,12 @@ import json
 
 import yaml
 
-from maasserver.api.doc_oapi import _render_oapi_paths, endpoint, landing_page
+from maasserver.api.doc_oapi import (
+    _prettify,
+    _render_oapi_paths,
+    endpoint,
+    landing_page,
+)
 from maasserver.models.config import Config
 from maasserver.testing.factory import factory
 from maasserver.testing.testcase import MAASServerTestCase
@@ -105,3 +110,40 @@ class TestOAPISpec(MAASServerTestCase):
         for k, v in _get_all_key_values(_render_oapi_paths()):
             if k == "type":
                 self.assertIn(v, self.oapi_types)
+
+
+class TestPrettify(MAASTestCase):
+    maxDiff = None
+
+    def test_cleans_newlines(self):
+        before = """\
+Returns system details -- for example, LLDP and
+
+``lshw`` XML dumps.
+
+
+Returns a ``{detail_type: xml, ...}`` map, where
+
+``detail_type`` is something like "lldp" or "lshw".
+
+
+Note that this is returned as BSON and not JSON. This is for
+
+efficiency, but mainly because JSON can''t do binary content without
+
+applying additional encoding like base-64. The example output below is
+
+represented in ASCII using ``bsondump example.bson`` and is for
+
+demonstrative purposes."""
+
+        after = """\
+Returns system details -- for example, LLDP and ``lshw`` XML dumps.
+
+
+Returns a ``{detail_type: xml, ...}`` map, where ``detail_type`` is something like "lldp" or "lshw".
+
+
+Note that this is returned as BSON and not JSON. This is for efficiency, but mainly because JSON can''t do binary content without applying additional encoding like base-64. The example output below is represented in ASCII using ``bsondump example.bson`` and is for demonstrative purposes."""
+
+        self.assertEqual(_prettify(before), after)