Migration guide for 0.4 (#4765)

* readme start * Enhance migration guide with organization overview and section breakdown * update toc * Update * wip * wip * WIP * Finished draft * add statement * Update migration guide for v0.4: refine language and clarify PyPI package ownership * wip * mv * Update * wip * Add lint for markdown files; fix lint errors * Fix indent * Fix syntax * Fix * Update python/check_md_code_blocks.py Co-authored-by: Copilot <[email protected]> * wip * WIP * wip * fix links * update * Add 0.4 component config example * update * update * update * add conversion function * wip * Move * Update * Update * update * Make buttons side by side * Update * small edits * wip --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Jack Gerrits <[email protected]> Co-authored-by: Jack Gerrits <[email protected]>
microsoft · Dec 30, 2024 · 156c3f1 · 156c3f1
1 parent c58eb9d
commit 156c3f1
Show file tree

Hide file tree

Showing 8 changed files with 1,372 additions and 6 deletions.
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
@@ -173,6 +173,24 @@ jobs:
           source ${{ github.workspace }}/python/.venv/bin/activate
           poe --directory ${{ matrix.package }} docs-check-examples
         working-directory: ./python
+
+  markdown-code-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --locked --all-extras
+        working-directory: ./python
+      - name: Run task
+        run: |
+          source ${{ github.workspace }}/python/.venv/bin/activate
+          poe markdown-code-lint
+        working-directory: ./python
 
   check-proto-changes-python:
     runs-on: ubuntu-latest

diff --git a/python/README.md b/python/README.md
@@ -5,6 +5,10 @@
 
 This directory works as a single `uv` workspace containing all project packages. See [`packages`](./packages/) to discover all project packages.
 
+## Migrating from 0.2.x?
+
+Please refer to the [migration guide](./migration_guide.md) for how to migrate your code from 0.2.x to 0.4.x.
+
 ## Development
 
 **TL;DR**, run all checks with:

diff --git a/python/check_md_code_blocks.py b/python/check_md_code_blocks.py
@@ -0,0 +1,82 @@
+"""Check code blocks in Markdown files for syntax errors."""
+
+import argparse
+import logging
+import tempfile
+from typing import List, Tuple
+
+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)
+
+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, "r", encoding="utf-8") as file:
+        lines = file.readlines()
+
+    code_blocks: List[Tuple[str, int]] = []
+    in_code_block = False
+    current_block: List[str] = []
+
+    for i, line in enumerate(lines):
+        if line.strip().startswith("```python"):
+            in_code_block = True
+            current_block = []
+        elif line.strip().startswith("```"):
+            in_code_block = False
+            code_blocks.append(("\n".join(current_block), i - len(current_block) + 1))
+        elif in_code_block:
+            current_block.append(line)
+
+    return code_blocks
+
+def check_code_blocks(markdown_file_paths: List[str]) -> None:
+    """Check Python code blocks in a Markdown file for syntax errors."""
+    files_with_errors = []
+
+    for markdown_file_path in markdown_file_paths:
+        code_blocks = extract_python_code_blocks(markdown_file_path)
+        had_errors = False
+        for code_block, line_no in code_blocks:
+            markdown_file_path_with_line_no = f"{markdown_file_path}:{line_no}"
+            logger.info("Checking a code block in %s...", markdown_file_path_with_line_no)
+
+            # Skip blocks that don't import autogen_agentchat, autogen_core, or autogen_ext
+            if all(all(import_code not in code_block for import_code in [f"import {module}", f"from {module}"]) for module in ["autogen_agentchat", "autogen_core", "autogen_ext"]):
+                logger.info(" " + darkgreen("OK[ignored]"))
+                continue
+
+            with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as temp_file:
+                temp_file.write(code_block.encode("utf-8"))
+                temp_file.flush()
+
+                # Run pyright on the temporary file using subprocess.run
+                import subprocess
+
+                result = subprocess.run(["pyright", temp_file.name], capture_output=True, text=True)
+                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)
+                    had_errors = True
+                else:
+                    logger.info(" " + darkgreen("OK"))
+
+        if had_errors:
+            files_with_errors.append(markdown_file_path)
+
+    if files_with_errors:
+        raise RuntimeError("Syntax errors found in the following files:\n" + "\n".join(files_with_errors))
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Check code blocks in Markdown files for syntax errors.")
+    # Argument is a list of markdown files containing glob patterns
+    parser.add_argument("markdown_files", nargs="+", help="Markdown files to check.")
+    args = parser.parse_args()
+    check_code_blocks(args.markdown_files)
diff --git a/python/packages/autogen-core/docs/src/index.md b/python/packages/autogen-core/docs/src/index.md
@@ -65,11 +65,8 @@ pip install "autogen-agentchat==0.4.0.dev12"
 
 +++
 
-```{button-ref} user-guide/agentchat-user-guide/quickstart
-:color: secondary
-
-Get Started
-```
+<a class="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary reference internal" href="user-guide/agentchat-user-guide/quickstart.html"><span class="doc">Get Started</span></a>
+<a class="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary reference internal" href="user-guide/agentchat-user-guide/migration-guide.html"><span class="doc">Migration Guide (0.2.x to 0.4.x)</span></a>
 
 :::
 :::{grid-item-card} {fas}`palette;pst-color-primary` Studio

diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md
@@ -42,6 +42,12 @@ Step-by-step guide to using AgentChat
 
 Sample code and use cases
 :::
+
+:::{grid-item-card} {fas}`truck-moving;pst-color-primary` Migration Guide
+:link: ./migration-guide.html
+
+How to migrate from AutoGen 0.2.x to 0.4.x.
+:::
 ::::
 
 ```{toctree}
@@ -50,6 +56,7 @@ Sample code and use cases
 
 installation
 quickstart
+migration-guide
 ```
 
 ```{toctree}