Fix relocated files help display. (#12185)

- Adjust for the fact that indented text is treated
  by readme.com as a blockquote, even inside `<p></p>`.
- Fix an empty string that caused a 500 error on readme.com
  (they cannot handle `<code></code>` with no content for some reason).

[ci skip-rust]

[ci skip-build-wheels]

build-support/bin/docs_templates/target_reference.md.mustache

@@ -1,13 +1,11 @@
-{{! Mark as a paragraph to render as plain text, rather than markdown. The spaces matter. }}
-<p> {{{description}}} </p>
+{{{description}}}
 
 {{#fields}}
 ## <code>{{alias}}</code>
 
 <span style="color: purple">type: <code>{{type_hint}}</code></span>
 <span style="color: green">{{{default_or_required}}}</span>
 
-{{! Mark as a paragraph to render as plain text, rather than markdown. The spaces matter. }}
-<p> {{{description}}} </p>
+{{{description}}}
 
 {{/fields}}

build-support/bin/generate_docs.py

@@ -79,6 +79,18 @@ def html_safe(s: str) -> str:
     return _backtick_re.sub(r"<code>\1</code>", html.escape(s))
 
 
+def description_safe(s: str) -> str:
+    """Escapes special characters in description text.
+
+    Descriptions are generally treated as plain text, not as markdown. But readme.com still renders
+    indented lines as blockquotes, so we must take care not to html-quote inside those.
+    """
+    safe_lines = [line if line.startswith("    ") else html_safe(line) for line in s.splitlines()]
+    safe_lines_str = "\n".join(safe_lines)
+    # Mark as a paragraph to render as plain text, rather than markdown. The spaces matter.
+    return f"<p> {safe_lines_str} </p>"
+
+
 def create_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Generate the Pants reference markdown files.")
     parser.add_argument(
@@ -218,11 +230,9 @@ def process_targets_input(cls, help_info: Dict) -> Dict[str, Dict[str, Any]]:
                 field["default_or_required"] = (
                     "required" if field["required"] else f"default: <code>{default_str}</code>"
                 )
-                # Description is not rendered as markdown, so we don't want to escape
-                # markdown special characters here (or the escapes will be visible).
-                field["description"] = html_safe(str(field["description"]))
+                field["description"] = description_safe(str(field["description"]))
             target["fields"] = sorted(target["fields"], key=lambda fld: cast(str, fld["alias"]))
-            target["description"] = html_safe(str(target["description"]))
+            target["description"] = description_safe(str(target["description"]))
 
         return cast(Dict[str, Dict[str, Any]], target_info)
 

src/python/pants/core/target_types.py

@@ -80,9 +80,8 @@ class RelocatedFilesSrcField(StringField):
     required = True
     help = (
         "The original prefix that you want to replace, such as `src/resources`.\n\nYou can set "
-        "this field to `"
-        "` to preserve the original path; the value in the `dest` field will "
-        "then be added to the beginning of this original path."
+        "this field to the empty string to preserve the original path; the value in the `dest` "
+        "field will then be added to the beginning of this original path."
     )
 
 
@@ -91,8 +90,8 @@ class RelocatedFilesDestField(StringField):
     required = True
     help = (
         "The new prefix that you want to add to the beginning of the path, such as `data`.\n\nYou "
-        'can set this field to "" to avoid adding any new values to the path; the value in the '
-        "`src` field will then be stripped, rather than replaced."
+        "can set this field to the empty string to avoid adding any new values to the path; the "
+        "value in the `src` field will then be stripped, rather than replaced."
     )