chore: use cog for quick README updates (#2428)

* chore: use cog for quick README updates

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* refactor: rename scripts

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

---------

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

bin/readme_changelog.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+
+import re
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).parent / ".."
+CHANGELOG_FILE = PROJECT_ROOT / "docs" / "changelog.md"
+
+# https://regexr.com/622ds
+FIRST_5_CHANGELOG_ENTRIES_REGEX = re.compile(r"""(^###.*?(?=###)){5}""", re.DOTALL | re.MULTILINE)
+
+
+def mini_changelog() -> str:
+    changelog_text = CHANGELOG_FILE.read_text()
+
+    mini_changelog_match = FIRST_5_CHANGELOG_ENTRIES_REGEX.search(changelog_text)
+    assert mini_changelog_match, "Failed to find the first few changelog entries"
+
+    return f"\n{mini_changelog_match.group(0).strip()}\n"
+
+
+if __name__ == "__main__":
+    print(mini_changelog())

bin/readme_options_table.py

@@ -1,13 +1,11 @@
 #!/usr/bin/env python3
 
-import argparse
 import dataclasses
 import re
 from pathlib import Path
 from typing import Final
 
 DIR: Final[Path] = Path(__file__).parent.parent.resolve()
-README: Final[Path] = DIR / "README.md"
 OPTIONS_MD: Final[Path] = DIR / "docs" / "options.md"
 
 SECTION_HEADER_REGEX = re.compile(r"^## (?P<name>.*?)$", re.MULTILINE)
@@ -17,11 +15,6 @@ OPTION_HEADER_REGEX = re.compile(
     r"^### (?P<name>.*?){.*#(?P<id>\S+).*}\n+> ?(?P<desc>.*)$", re.MULTILINE
 )
 
-README_OPTIONS_TABLE_SECTION = re.compile(
-    r"""(?<=<!-- START bin\/update_readme_options_table.py -->\n).*(?=<!-- END bin\/update_readme_options_table.py -->)""",
-    re.DOTALL,
-)
-
 
 @dataclasses.dataclass(kw_only=True)
 class Option:
@@ -31,17 +24,7 @@ class Option:
     section: str
 
 
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        description="Update the options table in the README from docs/options.md"
-    )
-    parser.add_argument(
-        "--force",
-        action="store_true",
-        help="Updates the README inplace, rather than printing to stdout.",
-    )
-    args = parser.parse_args()
-
+def get_table() -> str:
     options_md = OPTIONS_MD.read_text(encoding="utf-8")
 
     sections = SECTION_HEADER_REGEX.split(options_md)[1:]
@@ -58,7 +41,7 @@ def main() -> None:
             )
             options.append(option)
 
-    table_md = "<!-- This table is auto-generated from docs/options.md by bin/update_readme_options_table.py -->\n\n"
+    table_md = "\n<!-- This table is auto-generated from docs/options.md by bin/readme_options_table.py -->\n\n"
     table_md += "|   | Option | Description |\n"
     table_md += "|---|---|---|\n"
     last_section: str | None = None
@@ -78,21 +61,8 @@ def main() -> None:
         table_md += "| " + " | ".join(cells) + " |\n"
     table_md += "\n"
 
-    if not args.force:
-        print(table_md)
-        return
-
-    readme_text = README.read_text(encoding="utf-8")
-
-    if not re.search(README_OPTIONS_TABLE_SECTION, readme_text):
-        msg = "Options section not found in README"
-        raise ValueError(msg)
-
-    readme_text = re.sub(README_OPTIONS_TABLE_SECTION, table_md, readme_text)
-    README.write_text(readme_text, encoding="utf-8")
-
-    print("Updated README with options table.")
+    return table_md
 
 
 if __name__ == "__main__":
-    main()
+    print(get_table())

bin/update_readme_changelog.py

@@ -1,48 +0,0 @@
-#!/usr/bin/env python3
-
-
-import re
-import sys
-from pathlib import Path
-
-PROJECT_ROOT = Path(__file__).parent / ".."
-CHANGELOG_FILE = PROJECT_ROOT / "docs" / "changelog.md"
-README_FILE = PROJECT_ROOT / "README.md"
-
-# https://regexr.com/622ds
-FIRST_5_CHANGELOG_ENTRIES_REGEX = re.compile(r"""(^###.*?(?=###)){5}""", re.DOTALL | re.MULTILINE)
-
-# https://regexr.com/622e5
-README_CHANGELOG_SECTION = re.compile(
-    r"""(?<=<!-- START bin\/update_readme_changelog.py -->\n).*(?=<!-- END bin\/update_readme_changelog.py -->)""",
-    re.DOTALL,
-)
-
-
-def main() -> None:
-    changelog_text = CHANGELOG_FILE.read_text()
-    readme_text = README_FILE.read_text()
-
-    mini_changelog_match = FIRST_5_CHANGELOG_ENTRIES_REGEX.search(changelog_text)
-    assert mini_changelog_match, "Failed to find the first few changelog entries"
-
-    mini_changelog = "\n".join(
-        [
-            "",
-            "<!-- this section was generated by bin/update_readme_changelog.py -- do not edit manually -->",
-            "",
-            mini_changelog_match.group(0).strip(),
-            "",
-            "",
-        ]
-    )
-
-    if not re.search(README_CHANGELOG_SECTION, readme_text):
-        sys.exit("Changelog section not found in README")
-
-    readme_text = re.sub(README_CHANGELOG_SECTION, mini_changelog, readme_text)
-    README_FILE.write_text(readme_text)
-
-
-if __name__ == "__main__":
-    main()