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/packages/main/agent_framework/_memory.py

@@ -17,6 +17,8 @@ else:
 
 # region Context
 
+__all__ = ["AggregateContextProvider", "Context", "ContextProvider"]
+
 
 class Context(AFBaseModel):
     """A class containing any context that should be provided to the AI model as supplied by an ContextProvider.

python/packages/main/agent_framework/_tools.py

@@ -73,6 +73,9 @@ DEFAULT_MAX_ITERATIONS: Final[int] = 10
 TChatClient = TypeVar("TChatClient", bound="ChatClientProtocol")
 # region Helpers
 
+ArgsT = TypeVar("ArgsT", bound=BaseModel)
+ReturnT = TypeVar("ReturnT")
+
 
 def _parse_inputs(
     inputs: "Contents | dict[str, Any] | str | list[Contents | dict[str, Any] | str] | None",
@@ -121,13 +124,10 @@ def _parse_inputs(
 class ToolProtocol(Protocol):
     """Represents a generic tool that can be specified to an AI service.
 
-    Attributes:
+    Parameters:
         name: The name of the tool.
         description: A description of the tool.
         additional_properties: Additional properties associated with the tool.
-
-    Methods:
-        parameters: The parameters accepted by the tool, in a json schema format.
     """
 
     name: str
@@ -142,10 +142,6 @@ class ToolProtocol(Protocol):
         ...
 
 
-ArgsT = TypeVar("ArgsT", bound=BaseModel)
-ReturnT = TypeVar("ReturnT")
-
-
 class BaseTool(AFBaseModel):
     """Base class for AI tools, providing common attributes and methods.
 
@@ -516,11 +512,20 @@ def ai_function(
     In order to add descriptions to parameters, in your function signature,
     use the `Annotated` type from `typing` and the `Field` class from `pydantic`:
 
-            from typing import Annotated
+    Example:
 
+        .. code-block:: python
+
+            from typing import Annotated
             from pydantic import Field
 
-            <field_name>: Annotated[<type>, Field(description="<description>")]
+
+            def ai_function_example(
+                arg1: Annotated[str, Field(description="The first argument")],
+                arg2: Annotated[int, Field(description="The second argument")],
+            ) -> str:
+                # An example function that takes two arguments and returns a string.
+                return f"arg1: {arg1}, arg2: {arg2}"
 
     Args:
         func: The function to wrap. If None, returns a decorator.

python/packages/main/agent_framework/_types.py

@@ -1297,7 +1297,7 @@ FinishReason.TOOL_CALLS = FinishReason(value="tool_calls")  # type: ignore[assig
 
 
 class ChatMessage(AFBaseModel):
-    """Represents a chat message used by a `ModelClient`.
+    """Represents a chat message.
 
     Attributes:
         role: The role of the author of the message.