minor

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:

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)