Add a formatting step using mdformat as part of generate_mkdocs.py (#10484)

## Summary

The purpose of this change is mainly to address one of the issues
outlined in #10427. Namely, some lists in the docs were not rendering
properly when preceded by a text block without a newline character. This
PR adds `mdformat` as a final step to the rule documentation script, so
that any missing newlines will be added.

NB: The default behavior of `mdformat` is to escape markdown special
characters found in text such as `<`. This resulted in some misformatted
docs. To address this I implemented an ad-hoc mdformat plugin to
override the behavior. This may be considered a bit 'hacky', but I think
it's a good solution. Nevertheless, if someone has a better idea, let me
know.

## Test Plan

This change is hard to test systematically, however, I tried my best to
look at the before and after diffs to ensure no unwanted changes were
made to the docs.

scripts/generate_mkdocs.py

@@ -9,8 +9,11 @@ import subprocess
 from pathlib import Path
 from typing import NamedTuple
 
+import mdformat
 import yaml
 
+from _mdformat_utils import add_no_escape_text_plugin
+
 
 class Section(NamedTuple):
     """A section to include in the MkDocs documentation."""
@@ -140,6 +143,11 @@ def main() -> None:
 
             f.write(clean_file_content(file_content, title))
 
+    # Format rules docs
+    add_no_escape_text_plugin()
+    for rule_doc in Path("docs/rules").glob("*.md"):
+        mdformat.file(rule_doc, extensions=["mkdocs", "admonition", "no-escape-text"])
+
     with Path("mkdocs.template.yml").open(encoding="utf8") as fp:
         config = yaml.safe_load(fp)