From 1b3b118930d7dfff9dda296b06defcf83128d06a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ingo=20M=C3=BCller?= Date: Mon, 6 Jan 2025 14:25:20 +0000 Subject: [PATCH] docs: fix and simplify logic that generates extension options docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR fixes the logic in `generate_function_docs.py` that generates the docs for the options of functions. The previous version mixed up the option names and the corresponding choices, leading to non-sensical docs such as reported in #755. This PR collects the option names and corresponding choices jointly such that no mix-up can happen. I have looked at the output that is changed by this script but only superficially so: my impression is that (1) some options now come in a different order (because the previous order was determined by the order of keys in a `dict`, which is implementation-defined) and (2) the remaining changes come from the intention of this PR, i.e., the constitute fixes of previously non-sensical output. However, since I am not intrically familiar with all extension functions, I am not 100% sure. Signed-off-by: Ingo Müller --- .../docs/extensions/generate_function_docs.py | 22 +++++-------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/site/docs/extensions/generate_function_docs.py b/site/docs/extensions/generate_function_docs.py index 4f48b92af..7929ba929 100644 --- a/site/docs/extensions/generate_function_docs.py +++ b/site/docs/extensions/generate_function_docs.py @@ -40,8 +40,7 @@ def write_markdown(file_obj: dict, file_name: str) -> None: mdFile.new_paragraph("Implementations:") implementations_list = function_spec["impls"] option_names_list = [] - document_option_names_list = [] - options_list = [] + document_options = [] for count, impl in enumerate(implementations_list): if "args" not in impl: @@ -70,7 +69,6 @@ def write_markdown(file_obj: dict, file_name: str) -> None: # enum with no defined name, will be named as the list of choices if "name" in arg: option_name = str(arg["name"]) - document_option_names_list.append(option_name) else: option_name = choices @@ -78,7 +76,7 @@ def write_markdown(file_obj: dict, file_name: str) -> None: arg_string.append(option_name) arg_with_option_names.append(option_name) option_names_list.append(option_name) - options_list.append(choices) + document_options.append((option_name, choices)) else: raise Exception( f"Unrecognized argument found in " @@ -88,12 +86,11 @@ def write_markdown(file_obj: dict, file_name: str) -> None: opts = impl["options"] if "options" in impl else {} for opt_name, opt in opts.items(): choices = str(opt["values"]) - document_option_names_list.append(opt_name) + document_options.append((opt_name, choices)) option_name = f"option:{opt_name}" arg_string.append(option_name) arg_with_option_names.append(option_name) option_names_list.append(option_name) - options_list.append(choices) # If the implementation is variadic, the last argument will appear `min_args`, # number of times in the implementation. @@ -104,10 +101,6 @@ def write_markdown(file_obj: dict, file_name: str) -> None: if len(only_arg_names) > 0: only_arg_names.append(only_arg_names[-1]) - document_option_names_list = list( - dict.fromkeys(document_option_names_list) - ) - options_list = list(dict.fromkeys(options_list)) arg_values = [f"{x}" for x in arg_string] options_and_arg_names = [f"{x}" for x in arg_with_option_names] # reset the options names list for the next function implementation. @@ -151,14 +144,11 @@ def write_markdown(file_obj: dict, file_name: str) -> None: """ Write markdown for options. """ - if len(options_list) > 0 and len(document_option_names_list) > 0: + document_options = sorted(list(set(document_options))) + if len(document_options) > 0: mdFile.new_paragraph("
Options:") mdFile.write("\n") - A = options_list - B = document_option_names_list - for options_list, option_name in ( - zip(A, cycle(B)) if len(A) > len(B) else zip(cycle(A), B) - ): + for option_name, options_list in document_options: mdFile.new_line(f"
  • {option_name} {options_list}
    • ") mdFile.new_paragraph("
    ")