docs: Implement transpiler documentation improvements

[nagajaideep]

This PR implements a comprehensive refactoring of the ASTx transpiler architecture and significantly improves the documentation (README, docs/index.md, tutorials).

---

📌 Key Changes

• Architecture

  • Separated transpiler responsibilities:
    • python_to_ast.py → Handles ASTx → Python AST object conversion
    • python_string.py → Handles ASTx → Python source string generation
  • Removed circular dependencies between modules
  • Introduced clean separation of concerns for better maintainability

• Documentation

  • Expanded README.md with a dedicated transpiler section and examples
  • Updated docs/index.md to mirror README content (so GitHub and site docs stay aligned)
  • Added a full tutorial: docs/tutorials/astx_transpiler_refactor_tutorial.md
    • Covers step-by-step usage
    • Includes working examples and expected outputs

• Testing

  • Added/updated tests for both python_to_ast and python_string
  • Confirmed they run successfully in CI

---

✅ How to Test These Changes

Run transpiler tests

python -m pytest libs/astx-transpilers/tests/test_python_to_ast.py \
                 libs/astx-transpilers/tests/test_python_string.py -v

Run pre-commit hooks

pre-commit run --all-files

Manual usage

import astx
from astx_transpilers.python_string import ASTxPythonTranspiler

# Create function prototype
args = astx.Arguments(
    astx.Argument(name="x", type_=astx.Int32()),
    astx.Argument(name="y", type_=astx.Int32()),
)
fn_body = astx.Block()
fn_body.append(
    astx.FunctionReturn(
        value=astx.BinaryOp(op_code="+", lhs=astx.Variable("x"), rhs=astx.Variable("y"))
    )
)
add_function = astx.FunctionDef(
    prototype=astx.FunctionPrototype(name="add", args=args, return_type=astx.Int32()),
    body=fn_body,
)

# Transpile to Python code
transpiler = ASTxPythonTranspiler()
result = transpiler.visit(add_function)
print(result)

Expected Output:

def add(x: int, y: int) -> int:
    return (x + y)

---

📂 Files Changed

• README.md → Added transpiler section with usage example
• docs/index.md → Synced with README content
• docs/tutorials/astx_transpiler_refactor_tutorial.md → New detailed tutorial
• python_to_ast.py → AST conversion logic
• python_string.py → Python source generation logic
• Tests → Added/updated for both transpiler components

---

🌟 Benefits

• Cleaner transpiler design
• No circular dependencies
• Consistent documentation across README + docs site
• Clear usage examples and tutorial
• Easier onboarding for new contributors
• Extensible architecture for future backends

---

📝 Author’s Checklist

• Reviewed code and documentation changes
• Verified no typos or broken examples
• Code is well-commented in complex sections
• Tests pass locally
• Pre-commit hooks executed locally

---

🔍 Reviewer’s Checklist

• Able to reproduce problem locally from main
• Able to test new changes locally
• Confirm issues are fixed/resolved
• Verify documentation clarity and correctness
• Confirm transpiler architecture improvements are sound
• Ensure all tests pass and logs are generated if applicable

[xmnlab]

the readme files should be tracked

[xmnlab]

it should still be executed automatically