From a5bd7c4f0065861dd449c9036919f93e9b8b3714 Mon Sep 17 00:00:00 2001 From: Michael Frank <55284511+frank-at-adacore@users.noreply.github.com> Date: Tue, 4 Feb 2025 11:26:23 -0500 Subject: [PATCH 1/4] Update script to correctly handle new prelude style --- contrib/rst_update_prelude.py | 149 ++++++++++++++++++++++++---------- 1 file changed, 107 insertions(+), 42 deletions(-) diff --git a/contrib/rst_update_prelude.py b/contrib/rst_update_prelude.py index 5d1e57c45..46bdfdac7 100644 --- a/contrib/rst_update_prelude.py +++ b/contrib/rst_update_prelude.py @@ -1,3 +1,34 @@ +''' +Currently, every module needs to contain a 'prelude' that +is expected to have the same content across every module. +This script is designed to "fix" the prelude when +a required content is updated / added. + +To better organized this content, the default prelude +file uses RST containers to indicate where each specific +content begins. These sections are as follows: + BEGIN - any beginning matter + ROLES - common RST roles + SYMBOLS - common symbol replacements + REQUIRES - module-specific content + PROVIDES - module-specific content + END - end of prelude (contains the rest of the module). +In addition, anything appearing before BEGIN will be +saved as well. + +The general process is to use 'split' to break +the module into sections and use the prelude section +name as the key. Anything appearing before BEGIN +will use FIRST_KEY as the key. We then compare the +actual to expected content only for BEGIN, SYMBOLS, +and ROLES). If there is a difference, the actual +content is updated. (The remaing sections are considered +module-specific). +After comparison, the sections are written out in the +same order they were read in (either to stdout or +back to the original file). +''' + import os import sys import argparse @@ -6,16 +37,82 @@ CWD = Path(sys.argv[0]).resolve().parents[1] +''' +Flag used to split file into pieces +''' +PRELUDE_FLAG = "container:: PRELUDE " + +FIRST_KEY = '000' + +''' +Dictionary used to store expected prelude pieces +''' +EXPECTED = {} + + +''' +Populate the expected values from the predefined prelude +''' + +def load_prelude(filename): + global EXPECTED + + with open(filename, "rt") as file: + content = file.read() + pieces = content.split(PRELUDE_FLAG) + EXPECTED[FIRST_KEY] = pieces[0] + for section in pieces[1:]: + name, content = section.split("\n", 1) + EXPECTED[name] = content -def section_start(l): - # Section/Chapter/Slide separator - if len(l) > 2 and l[0] == l[1] and l[1] == l[2] and l[0] in "*-=+": - return True - # include another file - elif "include::" in l: - return True - return False +''' +Compare 'filename' contents to the expected contents. +If no changes are necessary, the file is not modified +''' + +def process_file(filename, in_place): + + ACTUAL = {} + pieces = None + update_required = False + + with open(filename, "rt") as file: + content = file.read() + pieces = content.split(PRELUDE_FLAG) + ACTUAL[FIRST_KEY] = pieces[0] + for section in pieces[1:]: + name, content = section.split("\n", 1) + ACTUAL[name] = content + + for key in ACTUAL.keys(): + if not key in EXPECTED.keys(): + if in_place: + print (" removing " + key) + del ACTUAL[key] + update_required = True + + elif key == 'BEGIN' or key == 'ROLES' or key == 'SYMBOLS': + if ACTUAL[key] != EXPECTED[key]: + if in_place: + print (" updating " + key) + ACTUAL[key] = EXPECTED[key] + update_required = True + + for key in EXPECTED.keys(): + if not key in ACTUAL.keys(): + if in_place: + print (" adding " + key) + ACTUAL[key] = EXPECTED[key] + update_required = True + + if update_required: + f_out = open(filename, "wt") if in_place else sys.stdout + for key in ACTUAL.keys(): + if key == FIRST_KEY: + f_out.write (ACTUAL[key]) + else: + f_out.write (PRELUDE_FLAG + key + "\n" + ACTUAL[key]) if __name__ == "__main__": ap = argparse.ArgumentParser() @@ -24,39 +121,7 @@ def section_start(l): ap.add_argument("files", nargs="+") args = ap.parse_args() - with open(args.prelude, "rt") as pf: - prelude_content = pf.read() - - if prelude_content.endswith(os.linesep): - prelude_content = prelude_content[:-1] + load_prelude(args.prelude) for f in args.files: - with open(f, "rt") as ff: - file_lines = ff.read().splitlines() - - f_out = open(f, "wt") if args.in_place else sys.stdout - - def print_out(*a, **kw): - kw.setdefault("file", f_out) - print(*a, **kw) - - STATE_INIT, STATE_CHAPTER, STATE_END = 0, 1, 2 - state = STATE_INIT - skip = 0 - for l in file_lines: - if skip: - skip -= 1 - print_out(l) - elif state == STATE_INIT: - if section_start(l): - state = STATE_CHAPTER - skip = 3 - print_out(l) - elif state == STATE_CHAPTER: - if section_start(l): - print_out(prelude_content) - print_out() - print_out(l) - state = STATE_END - elif state == STATE_END: - print_out(l) + process_file(f, args.in_place) From 5414dd68c4168f90734e54afc8b2e1f59657aa83 Mon Sep 17 00:00:00 2001 From: Michael Frank <55284511+frank-at-adacore@users.noreply.github.com> Date: Tue, 4 Feb 2025 11:39:48 -0500 Subject: [PATCH 2/4] Reformat according to 'black' --- contrib/rst_update_prelude.py | 37 +++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/contrib/rst_update_prelude.py b/contrib/rst_update_prelude.py index 46bdfdac7..6a13776af 100644 --- a/contrib/rst_update_prelude.py +++ b/contrib/rst_update_prelude.py @@ -1,4 +1,4 @@ -''' +""" Currently, every module needs to contain a 'prelude' that is expected to have the same content across every module. This script is designed to "fix" the prelude when @@ -27,7 +27,7 @@ After comparison, the sections are written out in the same order they were read in (either to stdout or back to the original file). -''' +""" import os import sys @@ -37,22 +37,23 @@ CWD = Path(sys.argv[0]).resolve().parents[1] -''' +""" Flag used to split file into pieces -''' +""" PRELUDE_FLAG = "container:: PRELUDE " -FIRST_KEY = '000' +FIRST_KEY = "000" -''' +""" Dictionary used to store expected prelude pieces -''' +""" EXPECTED = {} -''' +""" Populate the expected values from the predefined prelude -''' +""" + def load_prelude(filename): global EXPECTED @@ -66,10 +67,11 @@ def load_prelude(filename): EXPECTED[name] = content -''' +""" Compare 'filename' contents to the expected contents. If no changes are necessary, the file is not modified -''' +""" + def process_file(filename, in_place): @@ -88,21 +90,21 @@ def process_file(filename, in_place): for key in ACTUAL.keys(): if not key in EXPECTED.keys(): if in_place: - print (" removing " + key) + print(" removing " + key) del ACTUAL[key] update_required = True - elif key == 'BEGIN' or key == 'ROLES' or key == 'SYMBOLS': + elif key == "BEGIN" or key == "ROLES" or key == "SYMBOLS": if ACTUAL[key] != EXPECTED[key]: if in_place: - print (" updating " + key) + print(" updating " + key) ACTUAL[key] = EXPECTED[key] update_required = True for key in EXPECTED.keys(): if not key in ACTUAL.keys(): if in_place: - print (" adding " + key) + print(" adding " + key) ACTUAL[key] = EXPECTED[key] update_required = True @@ -110,9 +112,10 @@ def process_file(filename, in_place): f_out = open(filename, "wt") if in_place else sys.stdout for key in ACTUAL.keys(): if key == FIRST_KEY: - f_out.write (ACTUAL[key]) + f_out.write(ACTUAL[key]) else: - f_out.write (PRELUDE_FLAG + key + "\n" + ACTUAL[key]) + f_out.write(PRELUDE_FLAG + key + "\n" + ACTUAL[key]) + if __name__ == "__main__": ap = argparse.ArgumentParser() From e0a7c59ec0f535408cc4f1d8236d33c6836c2091 Mon Sep 17 00:00:00 2001 From: Michael Frank Date: Tue, 4 Feb 2025 18:48:57 +0000 Subject: [PATCH 3/4] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: Dana Binkley --- contrib/rst_update_prelude.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/rst_update_prelude.py b/contrib/rst_update_prelude.py index 6a13776af..e7daefb80 100644 --- a/contrib/rst_update_prelude.py +++ b/contrib/rst_update_prelude.py @@ -4,7 +4,7 @@ This script is designed to "fix" the prelude when a required content is updated / added. -To better organized this content, the default prelude +To better organize this content, the default prelude file uses RST containers to indicate where each specific content begins. These sections are as follows: BEGIN - any beginning matter From 4f232b6dd6ac87918f6be5272f9731cb4133ed63 Mon Sep 17 00:00:00 2001 From: Michael Frank Date: Tue, 4 Feb 2025 18:49:21 +0000 Subject: [PATCH 4/4] Apply 2 suggestion(s) to 1 file(s) Co-authored-by: Dana Binkley --- contrib/rst_update_prelude.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contrib/rst_update_prelude.py b/contrib/rst_update_prelude.py index e7daefb80..94a04c1b3 100644 --- a/contrib/rst_update_prelude.py +++ b/contrib/rst_update_prelude.py @@ -21,8 +21,8 @@ name as the key. Anything appearing before BEGIN will use FIRST_KEY as the key. We then compare the actual to expected content only for BEGIN, SYMBOLS, -and ROLES). If there is a difference, the actual -content is updated. (The remaing sections are considered +and ROLES). If there is a difference, the actual +content is updated. (The remaining sections are considered module-specific). After comparison, the sections are written out in the same order they were read in (either to stdout or