Add API documentation (#4798)

* Add API documentation

* Update python/packages/autogen-core/src/autogen_core/_cancellation_token.py

Co-authored-by: Eric Zhu <[email protected]>

---------

Co-authored-by: Eric Zhu <[email protected]>

python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md

@@ -1,3 +1,4 @@
+(agentid_and_lifecycle)=
 # Agent Identity and Lifecycle
 
 The agent runtime manages agents' identities

python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md

@@ -12,6 +12,7 @@ will handle their messages, and a workflow can be composed of agents
 with no inter-dependencies.
 This section focuses on the core concepts in broadcast: topic and subscription.
 
+(topic_and_subscription_topic)=
 ## Topic
 
 A topic defines the scope of a broadcast message.

python/packages/autogen-core/src/autogen_core/_agent_id.py

@@ -10,6 +10,12 @@ def is_valid_agent_type(value: str) -> bool:
 
 
 class AgentId:
+    """
+    Agent ID uniquely identifies an agent instance within an agent runtime - including distributed runtime. It is the 'address' of the agent instance for receiving messages.
+
+    See here for more information: :ref:`agentid_and_lifecycle`
+    """
+
     def __init__(self, type: str | AgentType, key: str) -> None:
         if isinstance(type, AgentType):
             type = type.type
@@ -36,6 +42,7 @@ def __eq__(self, value: object) -> bool:
 
     @classmethod
     def from_str(cls, agent_id: str) -> Self:
+        """Convert a string of the format ``type/key`` into an AgentId"""
         items = agent_id.split("/", maxsplit=1)
         if len(items) != 2:
             raise ValueError(f"Invalid agent id: {agent_id}")
@@ -44,8 +51,18 @@ def from_str(cls, agent_id: str) -> Self:
 
     @property
     def type(self) -> str:
+        """
+        An identifier that associates an agent with a specific factory function.
+
+        Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).
+        """
         return self._type
 
     @property
     def key(self) -> str:
+        """
+        Agent instance identifier.
+
+        Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).
+        """
         return self._key

python/packages/autogen-core/src/autogen_core/_agent_proxy.py

@@ -11,6 +11,8 @@
 
 
 class AgentProxy:
+    """A helper class that allows you to use an :class:`~autogen_core.AgentId` in place of its associated :class:`~autogen_core.Agent`"""
+
     def __init__(self, agent: AgentId, runtime: AgentRuntime):
         self._agent = agent
         self._runtime = runtime

python/packages/autogen-core/src/autogen_core/_cancellation_token.py

@@ -4,30 +4,36 @@
 
 
 class CancellationToken:
+    """A token used to cancel pending async calls"""
+
     def __init__(self) -> None:
         self._cancelled: bool = False
         self._lock: threading.Lock = threading.Lock()
         self._callbacks: List[Callable[[], None]] = []
 
     def cancel(self) -> None:
+        """Cancel pending async calls linked to this cancellation token."""
         with self._lock:
             if not self._cancelled:
                 self._cancelled = True
                 for callback in self._callbacks:
                     callback()
 
     def is_cancelled(self) -> bool:
+        """Check if the CancellationToken has been used"""
         with self._lock:
             return self._cancelled
 
     def add_callback(self, callback: Callable[[], None]) -> None:
+        """Attach a callback that will be called when cancel is invoked"""
         with self._lock:
             if self._cancelled:
                 callback()
             else:
                 self._callbacks.append(callback)
 
     def link_future(self, future: Future[Any]) -> Future[Any]:
+        """Link a pending async call to a token to allow its cancellation"""
         with self._lock:
             if self._cancelled:
                 future.cancel()

python/packages/autogen-core/src/autogen_core/_topic.py

@@ -10,6 +10,12 @@ def is_valid_topic_type(value: str) -> bool:
 
 @dataclass(eq=True, frozen=True)
 class TopicId:
+    """
+    TopicId defines the scope of a broadcast message. In essence, agent runtime implements a publish-subscribe model through its broadcast API: when publishing a message, the topic must be specified.
+
+    See here for more information: :ref:`topic_and_subscription_topic`
+    """
+
     type: str
     """Type of the event that this topic_id contains. Adhere's to the cloud event spec.
 
@@ -33,6 +39,7 @@ def __str__(self) -> str:
 
     @classmethod
     def from_str(cls, topic_id: str) -> Self:
+        """Convert a string of the format ``type/source`` into a TopicId"""
         items = topic_id.split("/", maxsplit=1)
         if len(items) != 2:
             raise ValueError(f"Invalid topic id: {topic_id}")