From 5785638ce3a655ed9f4ca03828bd252e6355f81d Mon Sep 17 00:00:00 2001 From: augustelalande Date: Mon, 18 Mar 2024 19:11:03 -0400 Subject: [PATCH 1/4] implement rule formatting using mdformat --- docs/requirements.txt | 3 +++ scripts/_utils.py | 34 ++++++++++++++++++++++++++++++++++ scripts/generate_mkdocs.py | 8 ++++++++ 3 files changed, 45 insertions(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index b60a10740a822..ea93e7d1cae57 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,3 +3,6 @@ black==23.10.0 mkdocs==1.5.0 mkdocs-material==9.1.18 mkdocs-redirects==1.2.1 +mdformat==0.7.17 +mdformat-mkdocs==2.0.4 +mdformat-admon==2.0.2 diff --git a/scripts/_utils.py b/scripts/_utils.py index 7871be6cd9787..ae846e51c8354 100644 --- a/scripts/_utils.py +++ b/scripts/_utils.py @@ -2,6 +2,15 @@ import re from pathlib import Path +from typing import TYPE_CHECKING + +import mdformat + +if TYPE_CHECKING: + import argparse + + from markdown_it import MarkdownIt + from mdformat.renderer import RenderContext, RenderTreeNode ROOT_DIR = Path(__file__).resolve().parent.parent @@ -24,3 +33,28 @@ def snake_case(name: str) -> str: def get_indent(line: str) -> str: return re.match(r"^\s*", line).group() # type: ignore[union-attr] + + +class NoEscapeTextPlugin: + """Overrides the default text formatting behavior of mdformat.""" + + def __init__(self: NoEscapeTextPlugin) -> None: + self.POSTPROCESSORS = {"text": NoEscapeTextPlugin.text} + self.RENDERERS = {} + + @staticmethod + def add_cli_options(parser: argparse.ArgumentParser) -> None: + pass + + @staticmethod + def update_mdit(mdit: MarkdownIt) -> None: + pass + + @staticmethod + def text(_text: str, node: RenderTreeNode, _context: RenderContext) -> str: + return node.content + + +def add_no_escape_text_plugin() -> None: + """Add NoEscapeTextPlugin to the list of mdformat extensions.""" + mdformat.plugins.PARSER_EXTENSIONS["no-escape-text"] = NoEscapeTextPlugin() diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py index d83fc62e117dd..0cc0533d1b8ca 100644 --- a/scripts/generate_mkdocs.py +++ b/scripts/generate_mkdocs.py @@ -9,8 +9,11 @@ from pathlib import Path from typing import NamedTuple +import mdformat import yaml +from _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) From 688ee1b2e750ddcb5ce61db865df80c554b2d954 Mon Sep 17 00:00:00 2001 From: augustelalande Date: Tue, 19 Mar 2024 21:33:32 -0400 Subject: [PATCH 2/4] move mdformat plugin to its own file --- scripts/_mdformat_utils.py | 36 ++++++++++++++++++++++++++++++++++++ scripts/_utils.py | 34 ---------------------------------- scripts/generate_mkdocs.py | 2 +- 3 files changed, 37 insertions(+), 35 deletions(-) create mode 100644 scripts/_mdformat_utils.py diff --git a/scripts/_mdformat_utils.py b/scripts/_mdformat_utils.py new file mode 100644 index 0000000000000..7ae6fbf37d719 --- /dev/null +++ b/scripts/_mdformat_utils.py @@ -0,0 +1,36 @@ +from __future__ import annotations + +from typing import TYPE_CHECKING + +import mdformat + +if TYPE_CHECKING: + import argparse + + from markdown_it import MarkdownIt + from mdformat.renderer import RenderContext, RenderTreeNode + + +class NoEscapeTextPlugin: + """Overrides the default text formatting behavior of mdformat.""" + + def __init__(self: NoEscapeTextPlugin) -> None: + self.POSTPROCESSORS = {"text": NoEscapeTextPlugin.text} + self.RENDERERS = {} + + @staticmethod + def add_cli_options(parser: argparse.ArgumentParser) -> None: + pass + + @staticmethod + def update_mdit(mdit: MarkdownIt) -> None: + pass + + @staticmethod + def text(_text: str, node: RenderTreeNode, _context: RenderContext) -> str: + return node.content + + +def add_no_escape_text_plugin() -> None: + """Add NoEscapeTextPlugin to the list of mdformat extensions.""" + mdformat.plugins.PARSER_EXTENSIONS["no-escape-text"] = NoEscapeTextPlugin() diff --git a/scripts/_utils.py b/scripts/_utils.py index ae846e51c8354..7871be6cd9787 100644 --- a/scripts/_utils.py +++ b/scripts/_utils.py @@ -2,15 +2,6 @@ import re from pathlib import Path -from typing import TYPE_CHECKING - -import mdformat - -if TYPE_CHECKING: - import argparse - - from markdown_it import MarkdownIt - from mdformat.renderer import RenderContext, RenderTreeNode ROOT_DIR = Path(__file__).resolve().parent.parent @@ -33,28 +24,3 @@ def snake_case(name: str) -> str: def get_indent(line: str) -> str: return re.match(r"^\s*", line).group() # type: ignore[union-attr] - - -class NoEscapeTextPlugin: - """Overrides the default text formatting behavior of mdformat.""" - - def __init__(self: NoEscapeTextPlugin) -> None: - self.POSTPROCESSORS = {"text": NoEscapeTextPlugin.text} - self.RENDERERS = {} - - @staticmethod - def add_cli_options(parser: argparse.ArgumentParser) -> None: - pass - - @staticmethod - def update_mdit(mdit: MarkdownIt) -> None: - pass - - @staticmethod - def text(_text: str, node: RenderTreeNode, _context: RenderContext) -> str: - return node.content - - -def add_no_escape_text_plugin() -> None: - """Add NoEscapeTextPlugin to the list of mdformat extensions.""" - mdformat.plugins.PARSER_EXTENSIONS["no-escape-text"] = NoEscapeTextPlugin() diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py index 0cc0533d1b8ca..2b61daec3e7e6 100644 --- a/scripts/generate_mkdocs.py +++ b/scripts/generate_mkdocs.py @@ -12,7 +12,7 @@ import mdformat import yaml -from _utils import add_no_escape_text_plugin +from _mdformat_utils import add_no_escape_text_plugin class Section(NamedTuple): From 851e38a7e462f2aab3dbceda301cbca245ae13d9 Mon Sep 17 00:00:00 2001 From: augustelalande Date: Tue, 19 Mar 2024 21:49:51 -0400 Subject: [PATCH 3/4] Add explanation for mdformat plugin --- scripts/_mdformat_utils.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/scripts/_mdformat_utils.py b/scripts/_mdformat_utils.py index 7ae6fbf37d719..8827551cbd85e 100644 --- a/scripts/_mdformat_utils.py +++ b/scripts/_mdformat_utils.py @@ -12,7 +12,15 @@ class NoEscapeTextPlugin: - """Overrides the default text formatting behavior of mdformat.""" + r"""Overrides the default text formatting behavior of mdformat. + + By default mdformat will escape any markdown special character found in a + text block, e.g., <. Some of these characters are found in our + documentation, and when escaped (i.e. \<) will be rendered incorrectly by + mkdocs, i.e., the backslash will appear in the render. Because our only + purpose in using mdformat is to manage the line-breaks, it makes sense to + override its text formatting behavior. + """ def __init__(self: NoEscapeTextPlugin) -> None: self.POSTPROCESSORS = {"text": NoEscapeTextPlugin.text} From 020a9a305ad3ff800345dd1a5d922a0f57d20b19 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Wed, 20 Mar 2024 20:29:59 -0400 Subject: [PATCH 4/4] Update insiders reqs --- docs/requirements-insiders.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/requirements-insiders.txt b/docs/requirements-insiders.txt index 354c982e0f1f9..acca188f4864d 100644 --- a/docs/requirements-insiders.txt +++ b/docs/requirements-insiders.txt @@ -3,3 +3,6 @@ black==23.10.0 mkdocs==1.5.0 mkdocs-material @ git+ssh://git@github.com/astral-sh/mkdocs-material-insiders.git@38c0b8187325c3bab386b666daf3518ac036f2f4 mkdocs-redirects==1.2.1 +mdformat==0.7.17 +mdformat-mkdocs==2.0.4 +mdformat-admon==2.0.2