From 9f4b1551f69363c74198d7c83a45adfb4749c7d8 Mon Sep 17 00:00:00 2001 From: Suneth Warnakulasuriya Date: Fri, 2 Feb 2024 22:55:27 +0100 Subject: [PATCH] minor --- .../Create_Content/Documentation_Pages.md | 5 +- docs/process_pages.py | 62 ++++++++++--------- 2 files changed, 38 insertions(+), 29 deletions(-) diff --git a/docs/pages/Kratos/Documentation_Guide/How_Tos/Create_Content/Documentation_Pages.md b/docs/pages/Kratos/Documentation_Guide/How_Tos/Create_Content/Documentation_Pages.md index 402992ff0b9f..df792f5f48dc 100644 --- a/docs/pages/Kratos/Documentation_Guide/How_Tos/Create_Content/Documentation_Pages.md +++ b/docs/pages/Kratos/Documentation_Guide/How_Tos/Create_Content/Documentation_Pages.md @@ -49,7 +49,10 @@ It is allowed to create subfolders to store page data such as ```images```. If t ## Python snippets -Python snippets can be added to markdown as usual. In this case, if one required to generate the output of the python snippet automatically and then to be added to the same markdown file, then ```## POST_PROCESS_PAGES_PYTHON_OUTPUT_GENERATION``` can be added somewhere within the python snippet. +Python snippets can be added to markdown as usual. In this case, if one requires to generate the output of the python snippet automatically and append after the python snippet, then following steps can be followed. +1. Add `## POST_PROCESS_PAGES_PYTHON_OUTPUT_GENERATION` anywhere in the python snippet. It should not have any leading or trailing spaces/tabs. +2. Run the local build in your computer [Make sure to initialize kratos environment or any other library environments in the terminal which is being used by the snippet]. This will run the snippet and capture the output. It will also remove the `## POST_PROCESS_PAGES_PYTHON_OUTPUT_GENERATION` tag line from the python snippet. +3. Now you will see some block after the python snippet which contains the python output. This generation is only done if ```process_pages.py``` is passed with `-t local` flag. Following is an example: diff --git a/docs/process_pages.py b/docs/process_pages.py index 8edb7f179730..ff87b73776a1 100644 --- a/docs/process_pages.py +++ b/docs/process_pages.py @@ -228,37 +228,43 @@ def AddPythonSnippetOutputs(file_path: Path) -> None: while index < len(lines): line = lines[index] index += 1 - output_lines.append(line) + if not found_python_snippet_block or line != "## POST_PROCESS_PAGES_PYTHON_OUTPUT_GENERATION\n": + output_lines.append(line) if found_python_snippet_block and line.startswith("```"): found_python_snippet_block = False if "## POST_PROCESS_PAGES_PYTHON_OUTPUT_GENERATION\n" in snippet_lines: - # create a temp file - temp_file_path = str(file_path.absolute()) + ".temp.py" - with open(temp_file_path, "w") as temp_file_output: - temp_file_output.writelines(snippet_lines) - - popen = subprocess.Popen(["python3", temp_file_path], stdout=subprocess.PIPE, universal_newlines=True) - - output_lines.append("\n") - output_lines.append("Expected output:\n") - output_lines.append("```bash\n") - for stdout_line in iter(popen.stdout.readline, ""): - output_lines.append(stdout_line) - output_lines.append("```\n") - - # remove the temp file - os.remove(temp_file_path) - - # now check this output already exists. then remove that output since - # this will be only called when processing is done with -t local flag. - # raise RuntimeError(lines[index:index+3]) - if lines[index:index+3] == ["\n", "Expected output:\n", "```bash\n"]: - while index < len(lines): - if lines[index] == "```\n": - index += 1 - break - index += 1 + # check whether existing expected output is found + temp_index = index + is_existing_output_found = False + while temp_index < len(lines): + if lines[temp_index].strip() != "": + is_existing_output_found = lines[temp_index] == "Expected output:\n" + is_existing_output_found &= lines[temp_index+1] == "```bash\n" + break + temp_index += 1 + + if not is_existing_output_found: + # existing is not found or force re-write is enabled + + # create a temp file + temp_file_path = str(file_path.absolute()) + ".temp.py" + with open(temp_file_path, "w") as temp_file_output: + temp_file_output.writelines(snippet_lines) + + popen = subprocess.Popen(["python3", temp_file_path], stdout=subprocess.PIPE, universal_newlines=True) + output_lines.append("\n") + output_lines.append("Expected output:\n") + output_lines.append("```bash\n") + for stdout_line in iter(popen.stdout.readline, ""): + output_lines.append(stdout_line) + output_lines.append("```\n") + + # remove the temp file + os.remove(temp_file_path) + + if is_existing_output_found: + index += temp_index + lines[temp_index:].index("```\n") + 1 if found_python_snippet_block: snippet_lines.append(line) @@ -326,4 +332,4 @@ def AddPythonSnippetOutputs(file_path: Path) -> None: # list_of_strings = CreateNavigatonBar(str(sub_itr_dir), 3, default_header_dict) # with open("_data/sidebars/{:s}.yml".format(menu_info["side_bar_name"]), "w") as file_output: # file_output.write("entries:\n") - # file_output.writelines(list_of_strings) + # file_output.writelines(list_of_strings) \ No newline at end of file