Skip to content

Commit

Permalink
Fix relocated files help display. (#12185)
Browse files Browse the repository at this point in the history
- 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]
  • Loading branch information
benjyw authored Jun 9, 2021
1 parent b971c85 commit 3adc0e0
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 13 deletions.
6 changes: 2 additions & 4 deletions build-support/bin/docs_templates/target_reference.md.mustache
Original file line number Diff line number Diff line change
@@ -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}}
18 changes: 14 additions & 4 deletions build-support/bin/generate_docs.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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)

Expand Down
9 changes: 4 additions & 5 deletions src/python/pants/core/target_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."
)


Expand All @@ -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."
)


Expand Down

0 comments on commit 3adc0e0

Please sign in to comment.