Python: api doc generation setup (#342)

* api doc generation setup

* remove old log file

* improved check md function

* update with sample code in docstring

* updated script

* docs update

* docs update and action

* removed all-extras

* fixed sync command

* moved install

* moved action

* renamed folder

* fixed syntax

* add python path

* fix mypy and reused steps

* updated merge test

* undo change

* slight update in poe commands

* dev setup update

* updated uvlock

python/check_md_code_blocks.py

@@ -3,19 +3,35 @@
 """Check code blocks in Markdown files for syntax errors."""
 
 import argparse
+from enum import Enum
 import logging
 import tempfile
+import subprocess  # nosec
 
 from pygments import highlight  # type: ignore
 from pygments.formatters import TerminalFormatter
 from pygments.lexers import PythonLexer
-from sphinx.util.console import darkgreen, darkred, faint, red, teal  # type: ignore[attr-defined]
 
 logger = logging.getLogger(__name__)
 logger.addHandler(logging.StreamHandler())
 logger.setLevel(logging.INFO)
 
 
+class Colors(str, Enum):
+    CEND = "\33[0m"
+    CRED = "\33[31m"
+    CREDBG = "\33[41m"
+    CGREEN = "\33[32m"
+    CGREENBG = "\33[42m"
+    CVIOLET = "\33[35m"
+    CGREY = "\33[90m"
+
+
+def with_color(text: str, color: Colors) -> str:
+    """Prints a string with the specified color."""
+    return f"{color.value}{text}{Colors.CEND.value}"
+
+
 def extract_python_code_blocks(markdown_file_path: str) -> list[tuple[str, int]]:
     """Extract Python code blocks from a Markdown file."""
     with open(markdown_file_path, encoding="utf-8") as file:
@@ -40,7 +56,7 @@ def extract_python_code_blocks(markdown_file_path: str) -> list[tuple[str, int]]
 
 def check_code_blocks(markdown_file_paths: list[str]) -> None:
     """Check Python code blocks in a Markdown file for syntax errors."""
-    files_with_errors = []
+    files_with_errors: list[str] = []
 
     for markdown_file_path in markdown_file_paths:
         code_blocks = extract_python_code_blocks(markdown_file_path)
@@ -54,7 +70,7 @@ def check_code_blocks(markdown_file_paths: list[str]) -> None:
                 all(import_code not in code_block for import_code in [f"import {module}", f"from {module}"])
                 for module in ["agent_framework"]
             ):
-                logger.info(" " + darkgreen("OK[ignored]"))
+                logger.info(f' {with_color("OK[ignored]", Colors.CGREENBG)}')
                 continue
 
             with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as temp_file:
@@ -62,17 +78,25 @@ def check_code_blocks(markdown_file_paths: list[str]) -> None:
                 temp_file.flush()
 
                 # Run pyright on the temporary file using subprocess.run
-                import subprocess  # nosec
 
                 result = subprocess.run(["pyright", temp_file.name], capture_output=True, text=True)  # nosec
                 if result.returncode != 0:
-                    logger.info(" " + darkred("FAIL"))
                     highlighted_code = highlight(code_block, PythonLexer(), TerminalFormatter())  # type: ignore
-                    output = f"{faint('========================================================')}\n{red('Error')}: Pyright found issues in {teal(markdown_file_path_with_line_no)}:\n{faint('--------------------------------------------------------')}\n{highlighted_code}\n{faint('--------------------------------------------------------')}\n\n{teal('pyright output:')}\n{red(result.stdout)}{faint('========================================================')}\n"
-                    logger.info(output)
+                    logger.info(
+                        f" {with_color('FAIL', Colors.CREDBG)}\n"
+                        f"{with_color('========================================================', Colors.CGREY)}\n"
+                        f"{with_color('Error', Colors.CRED)}: Pyright found issues in {with_color(markdown_file_path_with_line_no, Colors.CVIOLET)}:\n"
+                        f"{with_color('--------------------------------------------------------', Colors.CGREY)}\n"
+                        f"{highlighted_code}\n"
+                        f"{with_color('--------------------------------------------------------', Colors.CGREY)}\n"
+                        "\n"
+                        f"{with_color('pyright output:', Colors.CVIOLET)}\n"
+                        f"{with_color(result.stdout, Colors.CRED)}"
+                        f"{with_color('========================================================', Colors.CGREY)}\n"
+                    )
                     had_errors = True
                 else:
-                    logger.info(" " + darkgreen("OK"))
+                    logger.info(f" {with_color('OK', Colors.CGREENBG)}")
 
         if had_errors:
             files_with_errors.append(markdown_file_path)