Transition to Pydata Sphinx Theme (#482)

* add pydata theme dependencies

add some organization of current files to filt #362

add reference

remove jupyter-lite and jupyter-sphinx deps, update python docs to references/python

refactor docs to fit new top level architecture of user guide, contribution, packages and references

add sample switcher json

add skeleton for version switcher

add pointer to note on versioning

Update python/packages/autogen-core/docs/src/_static/switcher.json

Co-authored-by: Jack Gerrits <jackgerrits@users.noreply.github.com>

Update python/packages/autogen-core/docs/src/_static/switcher.json

Co-authored-by: Jack Gerrits <jackgerrits@users.noreply.github.com>

remove unused components

add privacy footer

hide previous and next button

remove 'Section Navigation' from sidebar

make packages a single page

general refactor, add missing items

remove unneeded sidebar conf

remove duplicate content on landing page

update landing page text.

general refactor, remove unreferences files, fix some build errors

* remove extra files

* move readme to correct location

* remove sidebar from packages page, layout updates

* update lock and add clean command

* remove discord

---------

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

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

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.

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,
+    }

python/packages/autogen-core/docs/src/_static/custom.css

@@ -0,0 +1,3 @@
+.bd-links__title {
+  display: none;
+}

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/"
+  }
+]

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 %}

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 %}
+

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",
-    "sphinxcontrib.apidoc",
-    "myst_nb",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.graphviz",
+    "sphinx_design",
+    "sphinxcontrib.apidoc",
+    "sphinx_copybutton",
+    "_extension.gallery_directive",
+    "myst_nb",
 ]
+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,
+    }

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>
+```   -->

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

@@ -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

python/packages/autogen-core/docs/src/other/CONTRIBUTING.md

@@ -1 +0,0 @@
-../../../../../../CONTRIBUTING.md

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)  "
+```

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
+```

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
+
+```

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/"

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"