API documentation page flattening (#4556)

* API documentation page refactor

* Fix links and unused pages

---------

Co-authored-by: Jack Gerrits <jack@jackgerrits.com>

python/.gitignore

@@ -161,7 +161,6 @@ cython_debug/
 
 .ruff_cache/
 
-/docs/src/reference
 .DS_Store
 
 # Generated log files

python/packages/autogen-agentchat/src/autogen_agentchat/__init__.py

@@ -1,6 +1,9 @@
 import importlib.metadata
 
 TRACE_LOGGER_NAME = "autogen_agentchat"
+"""Logger name for trace logs."""
+
 EVENT_LOGGER_NAME = "autogen_agentchat.events"
+"""Logger name for event logs."""
 
 __version__ = importlib.metadata.version("autogen_agentchat")

python/packages/autogen-core/.gitignore

@@ -161,7 +161,6 @@ cython_debug/
 
 .ruff_cache/
 
-/docs/src/reference/python
 .DS_Store
 
 # Generated log files

python/packages/autogen-core/docs/src/packages/index.md

@@ -34,7 +34,7 @@ Library that is at a similar level of abstraction as AutoGen 0.2, including defa
 pip install 'autogen-agentchat==0.4.0.dev8'
 ```
 
-[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/agentchat-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_agentchat/autogen_agentchat.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-agentchat/0.4.0.dev8/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-agentchat)
+[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/agentchat-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_agentchat.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-agentchat/0.4.0.dev8/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-agentchat)
 :::
 
 (pkg-info-autogen-core)=
@@ -49,7 +49,7 @@ Implements the core functionality of the AutoGen framework, providing basic buil
 pip install 'autogen-core==0.4.0.dev8'
 ```
 
-[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/core-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_core/autogen_core.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-core/0.4.0.dev8/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-core)
+[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/core-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_core.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-core/0.4.0.dev8/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-core)
 :::
 
 (pkg-info-autogen-ext)=
@@ -71,7 +71,7 @@ Extras:
 - `docker` needed for {py:class}`~autogen_ext.code_executors.DockerCommandLineCodeExecutor`
 - `openai` needed for {py:class}`~autogen_ext.models.OpenAIChatCompletionClient`
 
-[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/extensions-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_ext/autogen_ext.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-ext/0.4.0.dev8/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-ext)
+[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/extensions-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_ext.agents.web_surfer.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-ext/0.4.0.dev8/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-ext)
 :::
 
 (pkg-info-autogen-magentic-one)=

python/packages/autogen-core/docs/src/reference/index.md

@@ -11,24 +11,44 @@ myst:
 :hidden:
 :caption: AutoGen AgentChat
 
-python/autogen_agentchat/autogen_agentchat
+python/autogen_agentchat
+python/autogen_agentchat.messages
+python/autogen_agentchat.agents
+python/autogen_agentchat.teams
+python/autogen_agentchat.base
+python/autogen_agentchat.conditions
+python/autogen_agentchat.ui
+python/autogen_agentchat.state
 ```
 
 ```{toctree}
 :hidden:
 :caption: AutoGen Core
 
-python/autogen_core/autogen_core
+python/autogen_core
+python/autogen_core.components.models
+python/autogen_core.components.code_executor
+python/autogen_core.components.model_context
+python/autogen_core.components.tools
+python/autogen_core.components.tool_agent
+python/autogen_core.exceptions
+python/autogen_core.logging
 ```
 
 ```{toctree}
 :hidden:
 :caption: AutoGen Extensions
 
-python/autogen_ext/autogen_ext
+python/autogen_ext.agents.web_surfer
+python/autogen_ext.agents.file_surfer
+python/autogen_ext.agents.video_surfer
+python/autogen_ext.agents.video_surfer.tools
+python/autogen_ext.models
+python/autogen_ext.tools
+python/autogen_ext.runtimes.grpc
 ```
 
-::::{grid} 1 2 2 3
+<!-- ::::{grid} 1 2 2 3
 :margin: 4 4 0 0
 :gutter: 1
 
@@ -50,5 +70,4 @@ python/autogen_ext/autogen_ext
 :class-item: api-card
 :::
 
-::::
+:::: -->
-

python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.agents.rst

@@ -0,0 +1,8 @@
+autogen\_agentchat.agents
+=========================
+
+
+.. automodule:: autogen_agentchat.agents
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.base.rst

@@ -0,0 +1,8 @@
+autogen\_agentchat.base
+=======================
+
+
+.. automodule:: autogen_agentchat.base
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.conditions.rst

@@ -0,0 +1,8 @@
+autogen\_agentchat.conditions
+=============================
+
+
+.. automodule:: autogen_agentchat.conditions
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.messages.rst

@@ -0,0 +1,7 @@
+autogen\_agentchat.messages
+===========================
+
+.. automodule:: autogen_agentchat.messages
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.rst

@@ -0,0 +1,7 @@
+autogen\_agentchat
+==================
+
+.. automodule:: autogen_agentchat
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.state.rst

@@ -0,0 +1,8 @@
+autogen\_agentchat.state
+========================
+
+
+.. automodule:: autogen_agentchat.state
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.teams.rst

@@ -0,0 +1,8 @@
+autogen\_agentchat.teams
+========================
+
+
+.. automodule:: autogen_agentchat.teams
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_agentchat.ui.rst

@@ -0,0 +1,8 @@
+autogen\_agentchat.ui
+=====================
+
+
+.. automodule:: autogen_agentchat.ui
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_core.components.code_executor.rst

@@ -0,0 +1,8 @@
+autogen\_core.components.code\_executor
+=======================================
+
+
+.. automodule:: autogen_core.components.code_executor
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_core.components.model_context.rst

@@ -0,0 +1,8 @@
+autogen\_core.components.model\_context
+=======================================
+
+
+.. automodule:: autogen_core.components.model_context
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_core.components.models.rst

@@ -0,0 +1,8 @@
+autogen\_core.components.models
+===============================
+
+
+.. automodule:: autogen_core.components.models
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_core.components.tool_agent.rst

@@ -0,0 +1,8 @@
+autogen\_core.components.tool\_agent
+====================================
+
+
+.. automodule:: autogen_core.components.tool_agent
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_core.components.tools.rst

@@ -0,0 +1,8 @@
+autogen\_core.components.tools
+==============================
+
+
+.. automodule:: autogen_core.components.tools
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_core.exceptions.rst

@@ -0,0 +1,7 @@
+autogen\_core.exceptions
+========================
+
+.. automodule:: autogen_core.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_core.logging.rst

@@ -0,0 +1,7 @@
+autogen\_core.logging
+=====================
+
+.. automodule:: autogen_core.logging
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_core.rst

@@ -0,0 +1,8 @@
+autogen\_core
+=============
+
+
+.. automodule:: autogen_core
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_ext.agents.file_surfer.rst

@@ -0,0 +1,8 @@
+autogen\_ext.agents.file\_surfer
+================================
+
+
+.. automodule:: autogen_ext.agents.file_surfer
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_ext.agents.video_surfer.rst

@@ -0,0 +1,7 @@
+autogen\_ext.agents.video\_surfer
+=================================
+
+.. automodule:: autogen_ext.agents.video_surfer
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_ext.agents.video_surfer.tools.rst

@@ -0,0 +1,7 @@
+autogen\_ext.agents.video\_surfer.tools
+=======================================
+
+.. automodule:: autogen_ext.agents.video_surfer.tools
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_ext.agents.web_surfer.rst

@@ -0,0 +1,8 @@
+autogen\_ext.agents.web\_surfer
+===============================
+
+
+.. automodule:: autogen_ext.agents.web_surfer
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_ext.models.rst

@@ -0,0 +1,8 @@
+autogen\_ext.models
+===================
+
+
+.. automodule:: autogen_ext.models
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_ext.runtimes.grpc.rst

@@ -0,0 +1,7 @@
+autogen\_ext.runtimes.grpc
+==========================
+
+.. automodule:: autogen_ext.runtimes.grpc
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/docs/src/reference/python/autogen_ext.tools.rst

@@ -0,0 +1,8 @@
+autogen\_ext.tools
+==================
+
+
+.. automodule:: autogen_ext.tools
+   :members:
+   :undoc-members:
+   :show-inheritance:

python/packages/autogen-core/pyproject.toml

@@ -119,16 +119,7 @@ mypy.sequence = [
 ]
 
 # Docs
-docs-clean = "rm -rf docs/build && rm -rf docs/src/reference/python/"
+docs-clean = "rm -rf docs/build"
-
-docs-apidoc-core = "sphinx-apidoc --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_core src/autogen_core src/autogen_core/application/protos/"
-docs-apidoc-agentchat = "sphinx-apidoc --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_agentchat ../autogen-agentchat/src/autogen_agentchat"
-docs-apidoc-ext = "sphinx-apidoc --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_ext ../autogen-ext/src/autogen_ext ../autogen-ext/src/autogen_ext/code_executor ../autogen-ext/src/autogen_ext/tools/langchain"
-docs-apidoc-all = [
-    "docs-apidoc-core",
-    "docs-apidoc-agentchat",
-    "docs-apidoc-ext",
-]
 
 # Inline tables are WAY easier to read but for some reason they break pyright. So we have to write it out this way.
 # Example of inline table:
@@ -137,30 +128,11 @@ docs-apidoc-all = [
 #     { cmd = "sphinx-build docs/src docs/build" }
 # ]
 
-[[tool.poe.tasks.docs-build.sequence]]
+docs-build = "sphinx-build docs/src docs/build"
-ref = "docs-apidoc-all"
 
-[[tool.poe.tasks.docs-build.sequence]]
+docs-serve = "sphinx-autobuild --watch src docs/src docs/build --port 8000 --jobs auto"
-cmd = "sphinx-build docs/src docs/build"
 
-[[tool.poe.tasks.docs-serve.sequence]]
+docs-check = "sphinx-build --fail-on-warning docs/src docs/build"
-ref = "docs-apidoc-all"
 
-[[tool.poe.tasks.docs-serve.sequence]]
+docs-check-examples = "sphinx-build -b code_lint docs/src docs/build"
-cmd = "sphinx-autobuild --watch src docs/src docs/build --port 8000 --jobs auto"
-
-[[tool.poe.tasks.docs-check.sequence]]
-ref = "docs-apidoc-all"
-
-[[tool.poe.tasks.docs-check.sequence]]
-ref = "docs-apidoc-all"
-
-[[tool.poe.tasks.docs-check.sequence]]
-cmd = "sphinx-build --fail-on-warning docs/src docs/build"
-
-[[tool.poe.tasks.docs-check-examples.sequence]]
-ref = "docs-apidoc-all"
-
-[[tool.poe.tasks.docs-check-examples.sequence]]
-cmd = "sphinx-build -b code_lint docs/src docs/build"
 

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

@@ -12,7 +12,15 @@ from ._agent_type import AgentType
 from ._base_agent import BaseAgent
 from ._cancellation_token import CancellationToken
 from ._closure_agent import ClosureAgent, ClosureContext
-from ._constants import EVENT_LOGGER_NAME, ROOT_LOGGER_NAME, TRACE_LOGGER_NAME
+from ._constants import (
+    EVENT_LOGGER_NAME as EVENT_LOGGER_NAME_ALIAS,
+)
+from ._constants import (
+    ROOT_LOGGER_NAME as ROOT_LOGGER_NAME_ALIAS,
+)
+from ._constants import (
+    TRACE_LOGGER_NAME as TRACE_LOGGER_NAME_ALIAS,
+)
 from ._default_subscription import DefaultSubscription, default_subscription, type_subscription
 from ._default_topic import DefaultTopicId
 from ._image import Image
@@ -20,8 +28,12 @@ from ._message_context import MessageContext
 from ._message_handler_context import MessageHandlerContext
 from ._routed_agent import RoutedAgent, event, message_handler, rpc
 from ._serialization import (
-    JSON_DATA_CONTENT_TYPE,
+    JSON_DATA_CONTENT_TYPE as JSON_DATA_CONTENT_TYPE_ALIAS,
-    PROTOBUF_DATA_CONTENT_TYPE,
+)
+from ._serialization import (
+    PROTOBUF_DATA_CONTENT_TYPE as PROTOBUF_DATA_CONTENT_TYPE_ALIAS,
+)
+from ._serialization import (
     MessageSerializer,
     UnknownPayload,
     try_get_known_serializers_for_type,
@@ -34,6 +46,21 @@ from ._type_prefix_subscription import TypePrefixSubscription
 from ._type_subscription import TypeSubscription
 from ._types import FunctionCall
 
+EVENT_LOGGER_NAME = EVENT_LOGGER_NAME_ALIAS
+"""The name of the logger used for structured events."""
+
+ROOT_LOGGER_NAME = ROOT_LOGGER_NAME_ALIAS
+"""The name of the root logger."""
+
+TRACE_LOGGER_NAME = TRACE_LOGGER_NAME_ALIAS
+"""Logger name used for developer intended trace logging. The content and format of this log should not be depended upon."""
+
+JSON_DATA_CONTENT_TYPE = JSON_DATA_CONTENT_TYPE_ALIAS
+"""The content type for JSON data."""
+
+PROTOBUF_DATA_CONTENT_TYPE = PROTOBUF_DATA_CONTENT_TYPE_ALIAS
+"""The content type for Protobuf data."""
+
 __all__ = [
     "Agent",
     "AgentId",

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

@@ -92,8 +92,11 @@ def has_nested_base_model_in_type(tp: Any) -> bool:
 DataclassT = TypeVar("DataclassT", bound=IsDataclass)
 
 JSON_DATA_CONTENT_TYPE = "application/json"
+"""JSON data content type"""
+
 # TODO: what's the correct content type? There seems to be some disagreement over what it should be
 PROTOBUF_DATA_CONTENT_TYPE = "application/x-protobuf"
+"""Protobuf data content type"""
 
 
 class DataclassJsonMessageSerializer(MessageSerializer[DataclassT]):