Escape generated markdown values. (pantsbuild#11841)

This fixes various display bugs in our generated docs.

Also fixes a couple of issues with the doc generation script:

- Disables the remote auth plugin when running Pants to
  get help, since we disable the Pants plugin that provides it.
- Fix an issue with URL generation for subscopes.

[ci skip-rust]

[ci skip-build-wheels]

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

@@ -1,5 +1,5 @@
 {{! Mark as a paragraph to render as plain text, rather than markdown. }}
-<p>{{description}}</p>
+<p>{{{description}}}</p>
 
 {{#fields}}
 ## <code>{{alias}}</code>
@@ -8,6 +8,6 @@
 <span style="color: green">{{{default_or_required}}}</span>
 
 {{! Mark as a paragraph to render as plain text, rather than markdown. }}
-<p>{{description}}</p>
+<p>{{{description}}}</p>
 
 {{/fields}}

build-support/bin/generate_docs.py

@@ -12,7 +12,7 @@
     ./pants run build-support/bin/generate_docs.py -- --sync --api-key=<API_KEY>
 
 where API_KEY is your readme.io API Key, found here:
-  https://dash.readme.com/project/pants/v2.0/api-key
+  https://dash.readme.com/project/pants/v2.3/api-key
 """
 
 from __future__ import annotations
@@ -62,6 +62,14 @@ def determine_pants_version() -> str:
     return version
 
 
+_markdown_trans = str.maketrans({c: f"\\{c}" for c in "\\`*_"})
+
+
+def markdown_safe(s: str) -> str:
+    """Escapes special characters in s, so it can be used as a literal string in markdown."""
+    return html.escape(s.translate(_markdown_trans), quote=False)
+
+
 def create_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Generate the Pants reference markdown files.")
     parser.add_argument(
@@ -98,6 +106,7 @@ def run_pants_help_all() -> Dict:
         f"--backend-packages=-[{', '.join(map(repr, deactivated_backends))}]",
         f"--backend-packages=+[{', '.join(map(repr, activated_backends))}]",
         "--no-verify-config",
+        "--remote-auth-plugin= ",
         "help-all",
     ]
     run = subprocess.run(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, encoding="utf-8")
@@ -143,7 +152,8 @@ def get_tpl(name: str) -> str:
     @staticmethod
     def _link(scope: str, *, sync: bool) -> str:
         # docsite pages link to the slug, local pages to the .md source.
-        return f"reference-{scope}" if sync else f"{scope}.md"
+        url_safe_scope = scope.replace(".", "-")
+        return f"reference-{url_safe_scope}" if sync else f"{url_safe_scope}.md"
 
     @classmethod
     def process_options_input(cls, help_info: Dict, *, sync: bool) -> Dict:
@@ -168,7 +178,7 @@ def munge_option(option_data):
             # Munge the default so we can display it nicely when it's multiline, while
             # still displaying it inline if it's not.
             default_str = to_help_str(option_data["default"])
-            escaped_default_str = html.escape(default_str, quote=False)
+            escaped_default_str = markdown_safe(default_str)
             if "\n" in default_str:
                 option_data["marked_up_default"] = f"<pre>{escaped_default_str}</pre>"
             else:
@@ -190,11 +200,13 @@ def process_targets_input(cls, help_info: Dict) -> Dict[str, Dict[str, Any]]:
         for target in target_info.values():
             for field in target["fields"]:
                 # Combine the `default` and `required` properties.
-                default_str = html.escape(str(field["default"]), quote=False)
+                default_str = markdown_safe(str(field["default"]))
                 field["default_or_required"] = (
                     "required" if field["required"] else f"default: <code>{default_str}</code>"
                 )
+                field["description"] = markdown_safe(str(field["description"]))
             target["fields"] = sorted(target["fields"], key=lambda fld: cast(str, fld["alias"]))
+            target["description"] = markdown_safe(str(target["description"]))
 
         return cast(Dict[str, Dict[str, Any]], target_info)
 
@@ -412,7 +424,7 @@ def do_delete(doc_to_delete):
         for scope, shi in sorted(subsystems.items()):
             self._create(
                 parent_doc_id=all_subsystems_doc_id,
-                slug_suffix=scope,
+                slug_suffix=scope.replace(".", "-"),
                 title=scope,
                 body=self._render_options_body(shi),
             )

build-support/bin/generate_docs_test.py

@@ -0,0 +1,8 @@
+# Copyright 2021 Pants project contributors (see CONTRIBUTORS.md).
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+from generate_docs import markdown_safe
+
+
+def test_markdown_safe():
+    assert "\\*A\\_B&lt;C&amp;" == markdown_safe("*A_B<C&")

src/python/pants/option/global_options.py

@@ -175,6 +175,7 @@ def from_options(
         if (
             not local_only
             and bootstrap_options.remote_auth_plugin
+            and bootstrap_options.remote_auth_plugin.strip()
             and (remote_execution or remote_cache_read or remote_cache_write)
         ):
             if ":" not in bootstrap_options.remote_auth_plugin: