Ensure README is synched with code (#43)

* Ensure README is synched with code

* Use main function

* Add docstring to readme.py

* Compensate for regex substitution of \\ to \

Replacement strings used in regex substitution process backlash escapes
including R"\\". So we need to expand these to R"\\\\" before [1].

[1] https://docs.python.org/3/library/re.html#re.sub

* Make script independent of working directory

and pin paths relative to the scripts position. Should be a bit more
robust.

* Update README.md

Co-authored-by: Lars Grüter <lagru+github@mailbox.org>

* Refactor before expanding to other sections

* Expand to other sections

* Regenerate README

* Run linter

* Fix pre-commit hook for readme.py

* Fix comments

---------

Co-authored-by: Lars Grüter <lagru+github@mailbox.org>
Co-authored-by: Lars Grüter <lagru@mailbox.org>

.pre-commit-config.yaml

@@ -40,3 +40,11 @@ repos:
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: local
+    hooks:
+      - id: readme.py
+        name: readme.py
+        language: system
+        entry: python .tools/readme.py
+        files: "README.md|src/changelist/default_config.toml|.github/workflows/label-check.yaml|.github/workflows/milestone-merged-prs.yaml|.tools/readme.py"

.tools/readme.py

@@ -0,0 +1,55 @@
+"""Update README.md, used by pre-commit."""
+
+import re
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).parent.parent
+
+
+def get_section_info(file):
+    p = Path(file)
+    name = p.parts[-1]
+    ext = p.suffix[1:]
+    begin = rf"<!--- begin {name} --->\n"
+    end = rf"<!--- end {name} --->\n"
+
+    with open(PROJECT_ROOT / file) as fh:
+        section = fh.read()
+
+    if ext == "toml":
+        section = begin + rf"\n````{ext}\n" + section + r"````\n\n" + end
+    else:
+        section = begin + rf"\n```{ext}\n" + section + r"```\n\n" + end
+
+    return begin, end, section
+
+
+def main():
+    with open(PROJECT_ROOT / "README.md") as fh:
+        readme = fh.read()
+
+    # default_config.toml
+    begin, end, section = get_section_info("src/changelist/default_config.toml")
+    rx = re.compile(begin + ".*?" + end, re.DOTALL)
+    # Regex substitution replaces r"\\" with to r"\", compensate
+    section = section.replace(r"\\", r"\\\\")
+    readme = rx.sub(section, readme)
+
+    # label-check.yaml
+    begin, end, section = get_section_info(".github/workflows/label-check.yaml")
+    rx = re.compile(begin + ".*?" + end, re.DOTALL)
+    readme = rx.sub(section, readme)
+
+    # milestone-merged-prs.yaml
+    begin, end, section = get_section_info(
+        ".github/workflows/milestone-merged-prs.yaml"
+    )
+    rx = re.compile(begin + ".*?" + end, re.DOTALL)
+    readme = rx.sub(section, readme)
+
+    with open(PROJECT_ROOT / "README.md", "w") as fh:
+        fh.write(readme)
+
+
+if __name__ == "__main__":
+    main()

README.md

@@ -50,6 +50,9 @@ changelist can be configured from two sources, in order of precedence:
 If a configuration option is not specified in either file above, changelist
 falls back to the following configuration:
 
+<!--- Changes to the following block are overridden by a pre-commit hook! --->
+<!--- begin default_config.toml --->
+
 ````toml
 # Default changelist configuration as supported in pyproject.toml
 [tool.changelist]
@@ -109,6 +112,8 @@ pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*
 ".*Maintenance.*" = "Maintenance"
 ````
 
+<!--- end default_config.toml --->
+
 ## Set up your repository
 
 To categorize merged PRs in the changelist with the default configuration, each
@@ -122,14 +127,17 @@ we recommend adding an action that fails CI if the label is missing.
 
 To do so, place the following in `.github/workflows/label-check.yaml`:
 
+<!--- Changes to the following block are overridden by a pre-commit hook! --->
+<!--- begin label-check.yaml --->
+
 ```yaml
 name: Labels
 
 on:
   pull_request:
     types:
       - opened
-      - repoened
+      - reopened
       - labeled
       - unlabeled
       - synchronize
@@ -146,6 +154,8 @@ jobs:
         run: exit 1
 ```
 
+<!--- end label-check.yaml --->
+
 ### Milestones
 
 Often, it is helpful to have milestones that reflect the actual PRs
@@ -154,6 +164,9 @@ next open milestone to any merged PR.
 
 To do so, place the following in `.github/workflows/milestone-merged-prs.yaml`:
 
+<!--- Changes to the following block are overridden by a pre-commit hook! --->
+<!--- begin milestone-merged-prs.yaml --->
+
 ```yaml
 name: Milestone
 
@@ -175,4 +188,6 @@ jobs:
           force: true
 ```
 
+<!--- end milestone-merged-prs.yaml --->
+
 See https://github.com/scientific-python/attach-next-milestone-action for more information.