Skip to content

A programming framework for agentic AI

Transition to Pydata Sphinx Theme (#482)

Victor Dibiaeffde903c8e9
diff --git a/python/packages/autogen-core/.gitignore b/python/packages/autogen-core/.gitignore
index 186e847cc..81bcd42b6 100644
--- a/python/packages/autogen-core/.gitignore
+++ b/python/packages/autogen-core/.gitignore
@@ -161,7 +161,7 @@ cython_debug/
.ruff_cache/
-/docs/src/reference
+/docs/src/reference/python
.DS_Store
# Generated log files
diff --git a/python/packages/autogen-core/docs/README.md b/python/packages/autogen-core/docs/README.md
new file mode 100644
index 000000000..68ce29a9e
--- /dev/null
+++ b/python/packages/autogen-core/docs/README.md
@@ -0,0 +1,37 @@
+## Building the AGNext Documentation
+
+AGNext documentation is based on the sphinx documentation system and uses the myst-parser to render markdown files. It uses the [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/) to style the documentation.
+
+### Prerequisites
+
+Ensure you have all of the dev dependencies for the `autogen-core` package installed. You can install them by running the following command from the root of the python repository:
+
+```bash
+uv sync
+source .venv/bin/activate
+```
+
+## Building Docs
+
+To build the documentation, run the following command from the root of the python repository:
+
+```bash
+poe --directory ./packages/autogen-core/ docs-build
+```
+
+To serve the documentation locally, run the following command from the root of the python repository:
+
+```bash
+poe --directory ./packages/autogen-core/ docs-serve
+```
+
+[!NOTE]
+Sphinx will only rebuild files that have changed since the last build. If you want to force a full rebuild, you can delete the `./packages/autogen-core/docs/build` directory before running the `docs-build` command.
+
+## Versioning the Documentation
+
+The current theme - [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/) - supports [switching between versions](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html) of the documentation.
+
+To version the documentation, you need to create a new version of the documentation by copying the existing documentation to a new directory with the version number. For example, to create a new version of the documentation for version `0.1.0`, you would run the following command:
+
+How are various versions built? - TBD.
diff --git a/python/packages/autogen-core/docs/src/_extension/gallery_directive.py b/python/packages/autogen-core/docs/src/_extension/gallery_directive.py
new file mode 100644
index 000000000..80642c545
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/_extension/gallery_directive.py
@@ -0,0 +1,144 @@
+"""A directive to generate a gallery of images from structured data.
+
+Generating a gallery of images that are all the same size is a common
+pattern in documentation, and this can be cumbersome if the gallery is
+generated programmatically. This directive wraps this particular use-case
+in a helper-directive to generate it with a single YAML configuration file.
+
+It currently exists for maintainers of the pydata-sphinx-theme,
+but might be abstracted into a standalone package if it proves useful.
+"""
+
+from pathlib import Path
+from typing import Any, ClassVar, Dict, List
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from yaml import safe_load
+
+logger = logging.getLogger(__name__)
+
+
+TEMPLATE_GRID = """
+`````{{grid}} {columns}
+{options}
+
+{content}
+
+`````
+"""
+
+GRID_CARD = """
+````{{grid-item-card}} {title}
+{options}
+
+{content}
+````
+"""
+
+
+class GalleryGridDirective(SphinxDirective):
+ """A directive to show a gallery of images and links in a Bootstrap grid.
+
+ The grid can be generated from a YAML file that contains a list of items, or
+ from the content of the directive (also formatted in YAML). Use the parameter
+ "class-card" to add an additional CSS class to all cards. When specifying the grid
+ items, you can use all parameters from "grid-item-card" directive to customize
+ individual cards + ["image", "header", "content", "title"].
+
+ Danger:
+ This directive can only be used in the context of a Myst documentation page as
+ the templates use Markdown flavored formatting.
+ """
+
+ name = "gallery-grid"
+ has_content = True
+ required_arguments = 0
+ optional_arguments = 1
+ final_argument_whitespace = True
+ option_spec: ClassVar[dict[str, Any]] = {
+ # A class to be added to the resulting container
+ "grid-columns": directives.unchanged,
+ "class-container": directives.unchanged,
+ "class-card": directives.unchanged,
+ }
+
+ def run(self) -> List[nodes.Node]:
+ """Create the gallery grid."""
+ if self.arguments:
+ # If an argument is given, assume it's a path to a YAML file
+ # Parse it and load it into the directive content
+ path_data_rel = Path(self.arguments[0])
+ path_doc, _ = self.get_source_info()
+ path_doc = Path(path_doc).parent
+ path_data = (path_doc / path_data_rel).resolve()
+ if not path_data.exists():
+ logger.info(f"Could not find grid data at {path_data}.")
+ nodes.text("No grid data found at {path_data}.")
+ return
+ yaml_string = path_data.read_text()
+ else:
+ yaml_string = "\n".join(self.content)
+
+ # Use all the element with an img-bottom key as sites to show
+ # and generate a card item for each of them
+ grid_items = []
+ for item in safe_load(yaml_string):
+ # remove parameters that are not needed for the card options
+ title = item.pop("title", "")
+
+ # build the content of the card using some extra parameters
+ header = f"{item.pop('header')} \n^^^ \n" if "header" in item else ""
+ image = f"![image]({item.pop('image')}) \n" if "image" in item else ""
+ content = f"{item.pop('content')} \n" if "content" in item else ""
+
+ # optional parameter that influence all cards
+ if "class-card" in self.options:
+ item["class-card"] = self.options["class-card"]
+
+ loc_options_str = "\n".join(f":{k}: {v}" for k, v in item.items()) + " \n"
+
+ card = GRID_CARD.format(
+ options=loc_options_str, content=header + image + content, title=title
+ )
+ grid_items.append(card)
+
+ # Parse the template with Sphinx Design to create an output container
+ # Prep the options for the template grid
+ class_ = "gallery-directive" + f' {self.options.get("class-container", "")}'
+ options = {"gutter": 2, "class-container": class_}
+ options_str = "\n".join(f":{k}: {v}" for k, v in options.items())
+
+ # Create the directive string for the grid
+ grid_directive = TEMPLATE_GRID.format(
+ columns=self.options.get("grid-columns", "1 2 3 4"),
+ options=options_str,
+ content="\n".join(grid_items),
+ )
+
+ # Parse content as a directive so Sphinx Design processes it
+ container = nodes.container()
+ self.state.nested_parse([grid_directive], 0, container)
+
+ # Sphinx Design outputs a container too, so just use that
+ return [container.children[0]]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+ """Add custom configuration to sphinx app.
+
+ Args:
+ app: the Sphinx application
+
+ Returns:
+ the 2 parallel parameters set to ``True``.
+ """
+ app.add_directive("gallery-grid", GalleryGridDirective)
+
+ return {
+ "parallel_read_safe": True,
+ "parallel_write_safe": True,
+ }
diff --git a/python/packages/autogen-core/docs/src/_static/custom.css b/python/packages/autogen-core/docs/src/_static/custom.css
new file mode 100644
index 000000000..9daae5861
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/_static/custom.css
@@ -0,0 +1,3 @@
+.bd-links__title {
+ display: none;
+}
diff --git a/python/packages/autogen-core/docs/src/_static/switcher.json b/python/packages/autogen-core/docs/src/_static/switcher.json
new file mode 100644
index 000000000..b3c8d67dd
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/_static/switcher.json
@@ -0,0 +1,11 @@
+[
+ {
+ "name": "v0.2 (stable)",
+ "version": "0.2",
+ "url": "https://microsoft.github.io/autogen/en/0.2/"
+ },
+ {
+ "version": "dev",
+ "url": "https://microsoft.github.io/autogen/en/dev/"
+ }
+]
diff --git a/python/packages/autogen-core/docs/src/_templates/edit-this-page.html b/python/packages/autogen-core/docs/src/_templates/edit-this-page.html
new file mode 100644
index 000000000..0254d1a2a
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/_templates/edit-this-page.html
@@ -0,0 +1,16 @@
+{% if sourcename is defined and theme_use_edit_page_button and page_source_suffix %}
+ {% set src = sourcename.split('.') %}
+ <div class="tocsection editthispage">
+ <a href="{{ to_main(get_edit_provider_and_url()[1]) }}">
+ <i class="fa-solid fa-pencil"></i>
+ {% set provider = get_edit_provider_and_url()[0] %}
+ {% block edit_this_page_text %}
+ {% if provider %}
+ {% trans provider=provider %}Edit on {{ provider }}{% endtrans %}
+ {% else %}
+ {% trans %}Edit{% endtrans %}
+ {% endif %}
+ {% endblock %}
+ </a>
+ </div>
+{% endif %}
diff --git a/python/packages/autogen-core/docs/src/_templates/layout.html b/python/packages/autogen-core/docs/src/_templates/layout.html
new file mode 100644
index 000000000..af41810c7
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/_templates/layout.html
@@ -0,0 +1,30 @@
+{% extends "!layout.html" %}
+
+{% block footer %}
+<footer class="bd-footer">
+ <div class="container">
+ <div class="row">
+ <div class="col-12 col-md-4 mb-4 mb-md-0">
+ <h6>About</h5>
+ <p>&copy; 2024 Microsoft.</p>
+ </div>
+ <div class="col-6 col-md-4 mb-4 mb-md-0">
+ <h6>Links</h5>
+ <ul class="list-unstyled">
+ <li><a href="https://go.microsoft.com/fwlink/?LinkId=521839">Privacy Policy</a> | <a href="https://go.microsoft.com/fwlink/?linkid=2259814">Consumer Health Privacy</a> </li>
+
+ </ul>
+ </div>
+ <div class="col-6 col-md-4">
+ <h6>Community</h5>
+ <ul class="list-unstyled">
+ <li>
+ <a href="https://x.com/pyautogen" target="_blank">Twitter</a>
+ </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+</footer>
+{% endblock %}
+
diff --git a/python/packages/autogen-core/docs/src/conf.py b/python/packages/autogen-core/docs/src/conf.py
index 8cfe7353c..8736932e7 100644
--- a/python/packages/autogen-core/docs/src/conf.py
+++ b/python/packages/autogen-core/docs/src/conf.py
@@ -3,35 +3,53 @@
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import pydata_sphinx_theme
+from sphinx.application import Sphinx
+from typing import Any, Dict
+from pathlib import Path
+import sys
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
project = "autogen_core"
copyright = "2024, Microsoft"
author = "Microsoft"
+version = "0.2"
+
+
+sys.path.append(str(Path(".").resolve()))
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
+ "sphinx.ext.napoleon",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
- "sphinx.ext.napoleon",
+ "sphinx.ext.todo",
+ "sphinx.ext.viewcode",
+ "sphinx.ext.intersphinx",
+ "sphinx.ext.graphviz",
+ "sphinx_design",
"sphinxcontrib.apidoc",
+ "sphinx_copybutton",
+ "_extension.gallery_directive",
"myst_nb",
- "sphinx.ext.intersphinx",
]
+suppress_warnings = ["myst.header"]
apidoc_module_dir = "../../src/autogen_core"
-apidoc_output_dir = "reference"
+apidoc_output_dir = "reference/python"
apidoc_template_dir = "_apidoc_templates"
apidoc_separate_modules = True
+apidoc_toc_file = "index"
apidoc_extra_args = ["--no-toc"]
napoleon_custom_sections = [("Returns", "params_style")]
apidoc_excluded_paths = ["./application/protos/"]
-templates_path = []
-exclude_patterns = ["reference/autogen_core.rst"]
+templates_path = ["_templates"]
+exclude_patterns = ["reference/python/autogen_core.rst"]
autoclass_content = "init"
@@ -44,18 +62,60 @@ nb_execution_timeout = 60
myst_heading_anchors = 5
+
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_title = "AGNext"
-html_theme = "furo"
-html_static_path = []
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_sidebars = {'packages/index': []}
html_theme_options = {
- "source_repository": "https://github.com/microsoft/agnext",
- "source_branch": "main",
- "source_directory": "python/packages/autogen-core/docs/src/",
+
+ "header_links_before_dropdown": 4,
+ "navbar_align": "left",
+ "check_switcher": False,
+ # "navbar_start": ["navbar-logo", "version-switcher"],
+ # "switcher": {
+ # "json_url": "/_static/switcher.json",
+ # },
+ "show_prev_next": False,
+ ""
+ "icon_links": [
+ {
+ "name": "Twitter",
+ "url": "https://twitter.com/pyautogen",
+ "icon": "fa-brands fa-twitter",
+ },
+ {
+ "name": "GitHub",
+ "url": "https://github.com/microsoft/agnext",
+ "icon": "fa-brands fa-github",
+ },
+ {
+ "name": "PyPI",
+ "url": "https://pypi.org/project/autogen-core",
+ "icon": "fa-custom fa-pypi",
+ },
+ {
+ "name": "PyData",
+ "url": "https://pydata.org",
+ "icon": "fa-custom fa-pydata",
+ },
+ ],
+
+}
+
+
+html_context = {
+ 'display_github': True,
+ "github_user": "microsoft",
+ "github_repo": "agnext",
+ "github_version": "main",
+ "doc_path": "python/packages/autogen-core/docs/src/",
}
autodoc_default_options = {
@@ -64,3 +124,40 @@ autodoc_default_options = {
}
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+
+def setup_to_main(
+ app: Sphinx, pagename: str, templatename: str, context, doctree
+) -> None:
+ """Add a function that jinja can access for returning an "edit this page" link pointing to `main`."""
+
+ def to_main(link: str) -> str:
+ """Transform "edit on github" links and make sure they always point to the main branch.
+
+ Args:
+ link: the link to the github edit interface
+
+ Returns:
+ the link to the tip of the main branch for the same file
+ """
+ links = link.split("/")
+ idx = links.index("edit")
+ return "/".join(links[: idx + 1]) + "/main/" + "/".join(links[idx + 2:])
+
+ context["to_main"] = to_main
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+ """Add custom configuration to sphinx app.
+
+ Args:
+ app: the Sphinx application
+ Returns:
+ the 2 parallel parameters set to ``True``.
+ """
+ app.connect("html-page-context", setup_to_main)
+
+ return {
+ "parallel_read_safe": True,
+ "parallel_write_safe": True,
+ }
diff --git a/python/packages/autogen-core/docs/src/index.md b/python/packages/autogen-core/docs/src/index.md
new file mode 100644
index 000000000..71b95fcc6
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/index.md
@@ -0,0 +1,79 @@
+---
+myst:
+ html_meta:
+ "description lang=en": |
+ Top-level documentation for AGNext, a framework for building multi-agent applications with AI agents.
+html_theme.sidebar_secondary.remove: false
+---
+
+# AGNext
+
+AGNext is a OSS framework for developing intelligent applications using AI Agents patterns.
+It offers an easy way to quickly build event-driven, distributed, scalable, resilient AI agent systems. Agents are developed by using the [Actor model](https://en.wikipedia.org/wiki/Actor_model). You can build and run your agent system locally and easily move to a distributed system in the cloud when you are ready.
+
+Key features of AGNext are summarized below.
+
+```{gallery-grid}
+:grid-columns: 1 2 2 3
+
+- header: "{fas}`network-wired;pst-color-primary` Asynchronous Messaging"
+ content: "Agents communicate through asynchronous messages, enabling event-driven and request/response communication models."
+- header: "{fas}`cube;pst-color-primary` Scalable & Distributed"
+ content: "Enable complex scenarios with networks of agents across organizational boundaries."
+- header: "{fas}`code;pst-color-primary` Multi-Language Support"
+ content: "Python & Dotnet interoperating agents today, with more languages coming soon."
+- header: "{fas}`globe;pst-color-primary` Modular & Extensible"
+ content: "Highly customizable with features like custom agents, memory as a service, tools registry, and model library."
+- header: "{fas}`puzzle-piece;pst-color-primary` Observable & Debuggable"
+ content: "Easily trace and debug your agent systems."
+- header: "{fas}`project-diagram;pst-color-primary` Event-Driven Architecture"
+ content: "Build event-driven, distributed, scalable, and resilient AI agent systems."
+```
+
+<!--
+Key features of AGNext include:
+
+- Asynchronous messaging: Agents communicate with each other through asynchronous messages, enabling event-driven and request/response communication models.
+- Scalable & Distributed: Enable complex scenarios with networks of agents across org boundaries
+- Modular, extensible & highly customizable: E.g. custom agents, memory as a service, tools registry, model library
+- x-lang support: Python & Dotnet interoperating agents today, others coming soon
+- Observable, traceable & debuggable -->
+
+```{seealso}
+To start quickly, read the [Quick Start](user-guide/getting-started/quickstart) guide and follow the tutorial sections. To learn about the core concepts of AGNext, begin with [Agent and Multi-Agent Application](user-guide/core-concepts/agent-and-multi-agent-application).
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+user-guide/index
+```
+
+<!-- ## Community
+
+Information about the community that leads, supports, and develops AGNext.
+
+```{toctree}
+:maxdepth: 2
+
+community/index
+``` -->
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+packages/index
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+reference/index
+```
+
+<!-- ````{toctree}
+:hidden:
+
+Changelog <https://github.com/your-org/agnext/releases>
+``` -->
diff --git a/python/packages/autogen-core/docs/src/index.rst b/python/packages/autogen-core/docs/src/index.rst
deleted file mode 100644
index ac0a73f5b..000000000
--- a/python/packages/autogen-core/docs/src/index.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-AGNext
-------
-
-AGNext is a framework for building multi-agent applications with AI agents.
-
-At a high level, it provides a framework for inter-agent communication and a
-suite of independent components for building and managing agents.
-You can implement agents in
-different programming languages and deploy them on different machines across organizational boundaries.
-You can also implement agents using other agent frameworks and run them in AGNext.
-
-To start quickly, read the `Quick Start <getting-started/quickstart.html>`_ and
-follow the tutorial sections.
-
-To learn about the core concepts of AGNext, read the sections starting
-from `Agent and Multi-Agent Application <core-concepts/agent-and-multi-agent-application.html>`_.
-
-.. toctree::
- :caption: Core Concepts
- :hidden:
-
- core-concepts/agent-and-multi-agent-application
- core-concepts/architecture
- core-concepts/application-stack
- core-concepts/agent-identity-and-lifecycle
- core-concepts/topic-and-subscription
-
-.. toctree::
- :caption: Getting started
- :hidden:
-
- getting-started/installation
- getting-started/quickstart
- getting-started/agent-and-agent-runtime
- getting-started/message-and-communication
- getting-started/model-clients
- getting-started/tools
- getting-started/multi-agent-design-patterns
- getting-started/group-chat
- getting-started/reflection
-
-.. toctree::
- :caption: Guides
- :hidden:
-
- guides/logging
- guides/distributed-agent-runtime
- guides/telemetry
- guides/command-line-code-executors
-
-.. toctree::
- :caption: Cookbook
- :hidden:
-
- cookbook/azure-openai-with-aad-auth
- cookbook/termination-with-intervention
- cookbook/extracting-results-with-an-agent
- cookbook/openai-assistant-agent
- cookbook/langgraph-agent
- cookbook/llamaindex-agent
-
-
-.. toctree::
- :caption: Reference
- :hidden:
-
- reference/autogen_core.components
- reference/autogen_core.application
- reference/autogen_core.base
-
-.. toctree::
- :caption: Other
- :hidden:
-
- other/faqs
- other/contributing
diff --git a/python/packages/autogen-core/docs/src/other/CONTRIBUTING.md b/python/packages/autogen-core/docs/src/other/CONTRIBUTING.md
deleted file mode 120000
index 15d2819e4..000000000
--- a/python/packages/autogen-core/docs/src/other/CONTRIBUTING.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../../../../CONTRIBUTING.md
\ No newline at end of file
diff --git a/python/packages/autogen-core/docs/src/packages/index.md b/python/packages/autogen-core/docs/src/packages/index.md
new file mode 100644
index 000000000..33ea20074
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/packages/index.md
@@ -0,0 +1,24 @@
+---
+myst:
+ html_meta:
+ "description lang=en": |
+ AGNext packages provide a set of functionality for building multi-agent applications with AI agents.
+html_theme.nosidebar: true
+---
+
+# Packages
+
+AgNext offers a set of packages beginning with the `autogen-core` package. Each package is designed to provide a specific set of functionality.
+
+```{gallery-grid}
+:grid-columns: 1 2 2 3
+
+- header: "{fas}`cube;pst-color-primary` AutoGen Core"
+ content: "Implements the core functionality of the AGNext framework, providing basic building blocks for creating multi-agent systems. [PyPI](https://pypi.org/project/autogen-core/) | [Source](https://github.com/microsoft/agnext/tree/main/python/packages/autogen-core) "
+
+- header: "{fas}`users;pst-color-primary` TeamOne"
+ content: "A generalist multi-agent softbot utilizing five agents to tackle intricate tasks involving multi-step planning and real-world actions. [PyPI](https://pypi.org/project/teamone/) | [Source](https://github.com/microsoft/agnext/tree/main/python/packages/team-one) "
+
+- header: "{fas}`chart-bar;pst-color-primary` AgBench"
+ content: "AutoGenBench is a tool for repeatedly running pre-defined AutoGen tasks in tightly-controlled initial conditions. [PyPI](https://pypi.org/project/autogenbench/) | [Source](https://github.com/microsoft/agnext/tree/main/python/packages/agbench) "
+```
diff --git a/python/packages/autogen-core/docs/src/reference/index.md b/python/packages/autogen-core/docs/src/reference/index.md
new file mode 100644
index 000000000..acac42e6a
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/reference/index.md
@@ -0,0 +1,19 @@
+---
+myst:
+ html_meta:
+ "description lang=en": |
+ AGNext is a community-driven project. Learn how to get involved, contribute, and connect with the community.
+---
+
+# API Reference
+
+This section contains the API reference for the AGNext core package.
+
+```{toctree}
+:caption: Python API Reference
+:maxdepth: 1
+
+python/autogen_core.components
+python/autogen_core.application
+python/autogen_core.base
+```
diff --git a/python/packages/autogen-core/docs/src/cookbook/azure-openai-with-aad-auth.md b/python/packages/autogen-core/docs/src/user-guide/cookbook/azure-openai-with-aad-auth.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/cookbook/azure-openai-with-aad-auth.md
rename to python/packages/autogen-core/docs/src/user-guide/cookbook/azure-openai-with-aad-auth.md
diff --git a/python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/extracting-results-with-an-agent.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/cookbook/extracting-results-with-an-agent.ipynb
diff --git a/python/packages/autogen-core/docs/src/cookbook/langgraph-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/langgraph-agent.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/cookbook/langgraph-agent.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/cookbook/langgraph-agent.ipynb
diff --git a/python/packages/autogen-core/docs/src/cookbook/llamaindex-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/llamaindex-agent.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/cookbook/llamaindex-agent.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/cookbook/llamaindex-agent.ipynb
diff --git a/python/packages/autogen-core/docs/src/cookbook/openai-assistant-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/openai-assistant-agent.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/cookbook/openai-assistant-agent.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/cookbook/openai-assistant-agent.ipynb
diff --git a/python/packages/autogen-core/docs/src/cookbook/termination-with-intervention.ipynb b/python/packages/autogen-core/docs/src/user-guide/cookbook/termination-with-intervention.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/cookbook/termination-with-intervention.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/cookbook/termination-with-intervention.ipynb
diff --git a/python/packages/autogen-core/docs/src/core-concepts/agent-and-multi-agent-application.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-and-multi-agent-application.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/agent-and-multi-agent-application.md
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-and-multi-agent-application.md
diff --git a/python/packages/autogen-core/docs/src/core-concepts/agent-identity-and-lifecycle.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-identity-and-lifecycle.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/agent-identity-and-lifecycle.md
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-identity-and-lifecycle.md
diff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-application-stack.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-application-stack.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/agnext-application-stack.svg
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-application-stack.svg
diff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-architecture-distributed.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-architecture-distributed.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/agnext-architecture-distributed.svg
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-architecture-distributed.svg
diff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-architecture-standalone.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-architecture-standalone.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/agnext-architecture-standalone.svg
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-architecture-standalone.svg
diff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-code-gen-example.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-code-gen-example.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/agnext-code-gen-example.svg
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-code-gen-example.svg
diff --git a/python/packages/autogen-core/docs/src/core-concepts/agnext-layers.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-layers.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/agnext-layers.svg
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/agnext-layers.svg
diff --git a/python/packages/autogen-core/docs/src/core-concepts/application-stack.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/application-stack.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/application-stack.md
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/application-stack.md
diff --git a/python/packages/autogen-core/docs/src/core-concepts/architecture.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/architecture.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/architecture.md
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/architecture.md
diff --git a/python/packages/autogen-core/docs/src/other/faqs.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/faqs.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/other/faqs.md
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/faqs.md
diff --git a/python/packages/autogen-core/docs/src/core-concepts/subscription.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/subscription.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/subscription.svg
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/subscription.svg
diff --git a/python/packages/autogen-core/docs/src/core-concepts/topic-and-subscription.md b/python/packages/autogen-core/docs/src/user-guide/core-concepts/topic-and-subscription.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/topic-and-subscription.md
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/topic-and-subscription.md
diff --git a/python/packages/autogen-core/docs/src/core-concepts/type-subscription.svg b/python/packages/autogen-core/docs/src/user-guide/core-concepts/type-subscription.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/core-concepts/type-subscription.svg
rename to python/packages/autogen-core/docs/src/user-guide/core-concepts/type-subscription.svg
diff --git a/python/packages/autogen-core/docs/src/getting-started/agent-and-agent-runtime.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/agent-and-agent-runtime.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/agent-and-agent-runtime.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/agent-and-agent-runtime.ipynb
diff --git a/python/packages/autogen-core/docs/src/getting-started/coder-reviewer-data-flow.svg b/python/packages/autogen-core/docs/src/user-guide/getting-started/coder-reviewer-data-flow.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/coder-reviewer-data-flow.svg
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/coder-reviewer-data-flow.svg
diff --git a/python/packages/autogen-core/docs/src/getting-started/group-chat.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/group-chat.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/group-chat.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/group-chat.ipynb
diff --git a/python/packages/autogen-core/docs/src/getting-started/installation.md b/python/packages/autogen-core/docs/src/user-guide/getting-started/installation.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/installation.md
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/installation.md
diff --git a/python/packages/autogen-core/docs/src/getting-started/message-and-communication.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/message-and-communication.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/message-and-communication.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/message-and-communication.ipynb
diff --git a/python/packages/autogen-core/docs/src/getting-started/model-clients.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/model-clients.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/model-clients.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/model-clients.ipynb
diff --git a/python/packages/autogen-core/docs/src/getting-started/multi-agent-design-patterns.md b/python/packages/autogen-core/docs/src/user-guide/getting-started/multi-agent-design-patterns.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/multi-agent-design-patterns.md
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/multi-agent-design-patterns.md
diff --git a/python/packages/autogen-core/docs/src/getting-started/quickstart.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/quickstart.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/quickstart.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/quickstart.ipynb
diff --git a/python/packages/autogen-core/docs/src/getting-started/reflection.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/reflection.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/reflection.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/reflection.ipynb
diff --git a/python/packages/autogen-core/docs/src/getting-started/tool-use-agent-cfg.svg b/python/packages/autogen-core/docs/src/user-guide/getting-started/tool-use-agent-cfg.svg
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/tool-use-agent-cfg.svg
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/tool-use-agent-cfg.svg
diff --git a/python/packages/autogen-core/docs/src/getting-started/tools.ipynb b/python/packages/autogen-core/docs/src/user-guide/getting-started/tools.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/getting-started/tools.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/getting-started/tools.ipynb
diff --git a/python/packages/autogen-core/docs/src/guides/command-line-code-executors.ipynb b/python/packages/autogen-core/docs/src/user-guide/guides/command-line-code-executors.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/guides/command-line-code-executors.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/guides/command-line-code-executors.ipynb
diff --git a/python/packages/autogen-core/docs/src/guides/distributed-agent-runtime.ipynb b/python/packages/autogen-core/docs/src/user-guide/guides/distributed-agent-runtime.ipynb
similarity index 100%
rename from python/packages/autogen-core/docs/src/guides/distributed-agent-runtime.ipynb
rename to python/packages/autogen-core/docs/src/user-guide/guides/distributed-agent-runtime.ipynb
diff --git a/python/packages/autogen-core/docs/src/guides/logging.md b/python/packages/autogen-core/docs/src/user-guide/guides/logging.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/guides/logging.md
rename to python/packages/autogen-core/docs/src/user-guide/guides/logging.md
diff --git a/python/packages/autogen-core/docs/src/guides/telemetry.md b/python/packages/autogen-core/docs/src/user-guide/guides/telemetry.md
similarity index 100%
rename from python/packages/autogen-core/docs/src/guides/telemetry.md
rename to python/packages/autogen-core/docs/src/user-guide/guides/telemetry.md
diff --git a/python/packages/autogen-core/docs/src/user-guide/index.md b/python/packages/autogen-core/docs/src/user-guide/index.md
new file mode 100644
index 000000000..4b6c4f356
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/user-guide/index.md
@@ -0,0 +1,82 @@
+---
+myst:
+ html_meta:
+ "description lang=en": |
+ User Guide for AGNext, a framework for building multi-agent applications with AI agents.
+---
+
+# User Guide
+
+AGNext is a flexible framework for building multi-agent systems. Begin with the [installation](getting-started/installation.md) guide to set up the framework on your machine. Then, follow the [quickstart](getting-started/quickstart) guide to get started with building your first multi-agent application.
+
+```{danger}
+This project and documentation is a work in progress. If you have any questions or need help, please reach out to us on GitHub.
+```
+
+```{toctree}
+:caption: Getting Started
+:maxdepth: 1
+:hidden:
+
+getting-started/installation
+getting-started/quickstart
+```
+
+```{toctree}
+:caption: Core Concepts
+:maxdepth: 1
+:hidden:
+
+
+core-concepts/agent-and-multi-agent-application
+core-concepts/architecture
+core-concepts/application-stack
+core-concepts/agent-identity-and-lifecycle
+core-concepts/topic-and-subscription
+core-concepts/faqs
+
+```
+
+```{toctree}
+:caption: Framework
+:maxdepth: 1
+:hidden:
+getting-started/agent-and-agent-runtime
+getting-started/message-and-communication
+getting-started/model-clients
+getting-started/tools
+
+```
+
+```{toctree}
+:caption: Multi-Agent Design Patterns
+:maxdepth: 1
+:hidden:
+getting-started/multi-agent-design-patterns
+getting-started/group-chat
+getting-started/reflection
+```
+
+```{toctree}
+:caption: Cookbook
+:maxdepth: 1
+:hidden:
+cookbook/azure-openai-with-aad-auth
+cookbook/termination-with-intervention
+cookbook/extracting-results-with-an-agent
+cookbook/openai-assistant-agent
+cookbook/langgraph-agent
+cookbook/llamaindex-agent
+
+```
+
+```{toctree}
+:caption: Guides
+:maxdepth: 1
+:hidden:
+guides/logging
+guides/distributed-agent-runtime
+guides/telemetry
+guides/command-line-code-executors
+
+```
diff --git a/python/packages/autogen-core/pyproject.toml b/python/packages/autogen-core/pyproject.toml
index da9d71176..3e48b7af8 100644
--- a/python/packages/autogen-core/pyproject.toml
+++ b/python/packages/autogen-core/pyproject.toml
@@ -63,6 +63,9 @@ dev-dependencies = [
"types-docker",
"wikipedia",
"opentelemetry-sdk>=1.27.0",
+ "sphinx-design",
+ "pydata-sphinx-theme",
+ "sphinx-copybutton",
]
@@ -99,3 +102,4 @@ mypy.sequence = [
docs-build = "sphinx-build docs/src docs/build"
docs-serve = "sphinx-autobuild --watch src docs/src docs/build"
docs-check = "sphinx-build --fail-on-warning docs/src docs/build"
+docs-clean = "rm -rf docs/build && rm -rf docs/src/reference/python/"
diff --git a/python/uv.lock b/python/uv.lock
index ea0d59d01..608a8f2e9 100644
--- a/python/uv.lock
+++ b/python/uv.lock
@@ -46,6 +46,18 @@ requirements = [
{ name = "typer" },
]
+[[package]]
+name = "accessible-pygments"
+version = "0.0.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bc/c1/bbac6a50d02774f91572938964c582fff4270eee73ab822a4aeea4d8b11b/accessible_pygments-0.0.5.tar.gz", hash = "sha256:40918d3e6a2b619ad424cb91e556bd3bd8865443d9f22f1dcdf79e33c8046872", size = 1377899 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8d/3f/95338030883d8c8b91223b4e21744b04d11b161a3ef117295d8241f50ab4/accessible_pygments-0.0.5-py3-none-any.whl", hash = "sha256:88ae3211e68a1d0b011504b2ffc1691feafce124b845bd072ab6f9f66f34d4b7", size = 1395903 },
+]
+
[[package]]
name = "agbench"
version = "0.0.1a1"
@@ -323,10 +335,13 @@ dev = [
{ name = "opentelemetry-sdk" },
{ name = "pip" },
{ name = "polars" },
+ { name = "pydata-sphinx-theme" },
{ name = "python-dotenv" },
{ name = "requests" },
{ name = "sphinx" },
{ name = "sphinx-autobuild" },
+ { name = "sphinx-copybutton" },
+ { name = "sphinx-design" },
{ name = "sphinxcontrib-apidoc" },
{ name = "tavily-python" },
{ name = "textual" },
@@ -376,10 +391,13 @@ dev = [
{ name = "opentelemetry-sdk", specifier = ">=1.27.0" },
{ name = "pip" },
{ name = "polars" },
+ { name = "pydata-sphinx-theme" },
{ name = "python-dotenv" },
{ name = "requests" },
{ name = "sphinx" },
{ name = "sphinx-autobuild" },
+ { name = "sphinx-copybutton" },
+ { name = "sphinx-design" },
{ name = "sphinxcontrib-apidoc" },
{ name = "tavily-python" },
{ name = "textual" },
@@ -3151,6 +3169,25 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/af/93/06d44e08277b3b818b75bd5f25e879d7693e4b7dd3505fde89916fcc9ca2/pydantic_core-2.20.1-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:254ec27fdb5b1ee60684f91683be95e5133c994cc54e86a0b0963afa25c8f8a6", size = 1914966 },
]
+[[package]]
+name = "pydata-sphinx-theme"
+version = "0.15.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "accessible-pygments" },
+ { name = "babel" },
+ { name = "beautifulsoup4" },
+ { name = "docutils" },
+ { name = "packaging" },
+ { name = "pygments" },
+ { name = "sphinx" },
+ { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/67/ea/3ab478cccacc2e8ef69892c42c44ae547bae089f356c4b47caf61730958d/pydata_sphinx_theme-0.15.4.tar.gz", hash = "sha256:7762ec0ac59df3acecf49fd2f889e1b4565dbce8b88b2e29ee06fdd90645a06d", size = 2400673 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e7/d3/c622950d87a2ffd1654208733b5bd1c5645930014abed8f4c0d74863988b/pydata_sphinx_theme-0.15.4-py3-none-any.whl", hash = "sha256:2136ad0e9500d0949f96167e63f3e298620040aea8f9c74621959eda5d4cf8e6", size = 4640157 },
+]
+
[[package]]
name = "pydub"
version = "0.25.1"
@@ -4001,6 +4038,30 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/3c/dd/018ce05c532a22007ac58d4f45232514cd9d6dd0ee1dc374e309db830983/sphinx_basic_ng-1.0.0b2-py3-none-any.whl", hash = "sha256:eb09aedbabfb650607e9b4b68c9d240b90b1e1be221d6ad71d61c52e29f7932b", size = 22496 },
]
+[[package]]
+name = "sphinx-copybutton"
+version = "0.5.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "sphinx" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/fc/2b/a964715e7f5295f77509e59309959f4125122d648f86b4fe7d70ca1d882c/sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd", size = 23039 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/9e/48/1ea60e74949eecb12cdd6ac43987f9fd331156388dcc2319b45e2ebb81bf/sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e", size = 13343 },
+]
+
+[[package]]
+name = "sphinx-design"
+version = "0.6.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "sphinx" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2b/69/b34e0cb5336f09c6866d53b4a19d76c227cdec1bbc7ac4de63ca7d58c9c7/sphinx_design-0.6.1.tar.gz", hash = "sha256:b44eea3719386d04d765c1a8257caca2b3e6f8421d7b3a5e742c0fd45f84e632", size = 2193689 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c6/43/65c0acbd8cc6f50195a3a1fc195c404988b15c67090e73c7a41a9f57d6bd/sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c", size = 2215338 },
+]
+
[[package]]
name = "sphinxcontrib-apidoc"
version = "0.5.0"