In the currently published specification the data model definitions include a proto snippet and then have a list of fields under the snippet. This creates duplicated information. To prevent this duplication while maintaining an easy to read presentation of the abstract data models, this PR uses a Python macro to convert the proto into a markdown table. Also took the opportunity to do an editorial pass on the comments in the a2a.proto before the field descriptions were removed from the specification.md. Some of this content came from the types.ts file that often had information that was not in a2a.proto. A preview of the changes can be seen here https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#41-core-objects # Proto to Markdown Table Conversion The macro system provides two main functions (`proto_to_table` and `proto_enum_to_table`) that convert Protocol Buffer definitions into formatted markdown tables: 1. **Locates Definitions**: Reads the `.proto` file and uses region markers (`--8<-- [start:Name]` and `--8<-- [end:Name]`) to extract specific message or enum definitions. 2. **Parses Structure**: Analyzes the proto content to separate three sections: - **Description**: Comments appearing before the message/enum declaration - **Fields/Values**: The actual field or enum value definitions with their inline comments - **Notes**: Comments appearing after the closing brace 3. **Extracts Field Details**: For each field, it captures: - Field name (converted from snake_case to camelCase, or using `json_name` annotation) - Type (mapped to readable formats like "string", "array of integer", "map of string") - Required status (based on `REQUIRED` annotation or `optional` keyword) - Description (from preceding comment lines) 4. **Generates Output**: Assembles the markdown output with: - Description text at the top - A formatted table with columns for Field/Type/Required/Description (or Value/Description for enums) - Special notes for `oneof` groups - Additional notes from comments after the definition The conversion automatically handles multi-line field definitions, map types, repeated fields, and filters out protolint directives and region markers from the output. --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
180 lines
6.3 KiB
YAML
180 lines
6.3 KiB
YAML
# Project information
|
|
site_name: A2A Protocol
|
|
site_url: https://a2a-protocol.org/
|
|
site_description: >-
|
|
The official documentation for the Agent2Agent (A2A) protocol. The A2A protocol is an open standard that allows different AI agents to securely communicate, collaborate, and solve complex problems together.
|
|
site_author: The Linux Foundation
|
|
site_dir: site
|
|
edit_uri: edit/main/docs/
|
|
|
|
# Exclude files from the docs directory
|
|
exclude_docs: |
|
|
README.md
|
|
|
|
extra:
|
|
a2a_version: !ENV [MIKE_VERSION, "dev"]
|
|
analytics:
|
|
provider: google
|
|
property: G-RB39M83WHB
|
|
|
|
# Navigation
|
|
nav:
|
|
- Home: index.md
|
|
- Documentation:
|
|
- What is A2A?: topics/what-is-a2a.md
|
|
- Core Concepts: topics/key-concepts.md
|
|
- Agent Discovery: topics/agent-discovery.md
|
|
- Enterprise Features: topics/enterprise-ready.md
|
|
- Life of a Task: topics/life-of-a-task.md
|
|
- Extensions: topics/extensions.md
|
|
- Streaming & Asynchronous Operations: topics/streaming-and-async.md
|
|
- A2A and MCP: topics/a2a-and-mcp.md
|
|
- Tutorials and Samples:
|
|
- tutorials/index.md
|
|
- Quickstart (Python):
|
|
- Introduction: tutorials/python/1-introduction.md
|
|
- Setup: tutorials/python/2-setup.md
|
|
- Agent Skills & Agent Card: tutorials/python/3-agent-skills-and-card.md
|
|
- Agent Executor: tutorials/python/4-agent-executor.md
|
|
- Start Server: tutorials/python/5-start-server.md
|
|
- Interact with Server: tutorials/python/6-interact-with-server.md
|
|
- Streaming & Multiturn: tutorials/python/7-streaming-and-multiturn.md
|
|
- Next Steps: tutorials/python/8-next-steps.md
|
|
- Specification:
|
|
- Overview: specification.md
|
|
- Protocol Definition: definitions.md
|
|
- SDK Reference:
|
|
- sdk/index.md
|
|
- Python: sdk/python.md
|
|
- Community: community.md
|
|
- Partners: partners.md
|
|
- Roadmap: roadmap.md
|
|
|
|
# Repository
|
|
repo_name: a2aproject/A2A
|
|
repo_url: https://github.com/a2aproject/A2A
|
|
|
|
# Copyright
|
|
copyright: Copyright 2025 The Linux Foundation. Licensed under the Apache License, Version 2.0.
|
|
|
|
# Custom CSS
|
|
extra_css:
|
|
- stylesheets/custom.css
|
|
|
|
# Configuration
|
|
theme:
|
|
name: material
|
|
custom_dir: .mkdocs/overrides
|
|
font:
|
|
text: Google Sans
|
|
code: Roboto Mono
|
|
logo: assets/a2a-logo-white.svg
|
|
favicon: assets/a2a-logo-black.svg
|
|
icon:
|
|
repo: fontawesome/brands/github
|
|
view: material/pencil-box-multiple
|
|
admonition:
|
|
note: fontawesome/solid/note-sticky
|
|
abstract: fontawesome/solid/book
|
|
info: fontawesome/solid/circle-info
|
|
tip: fontawesome/solid/bullhorn
|
|
success: fontawesome/solid/check
|
|
question: fontawesome/solid/circle-question
|
|
warning: fontawesome/solid/triangle-exclamation
|
|
failure: fontawesome/solid/bomb
|
|
danger: fontawesome/solid/skull
|
|
bug: fontawesome/solid/robot
|
|
example: fontawesome/solid/flask
|
|
quote: fontawesome/solid/quote-left
|
|
palette:
|
|
- scheme: default
|
|
primary: indigo
|
|
accent: white
|
|
features:
|
|
- announce.dismiss
|
|
- content.action.view
|
|
- content.code.annotate
|
|
- content.code.copy
|
|
- content.code.select
|
|
- content.tabs.link
|
|
- navigation.footer
|
|
- navigation.indexes
|
|
- navigation.instant
|
|
- navigation.instant.progress
|
|
- navigation.path
|
|
- navigation.top
|
|
- navigation.tracking
|
|
- toc.follow
|
|
- versioning:
|
|
provider: mike
|
|
|
|
# Extensions
|
|
markdown_extensions:
|
|
- meta
|
|
- footnotes
|
|
- admonition
|
|
- attr_list
|
|
- md_in_html
|
|
- pymdownx.details
|
|
- pymdownx.emoji:
|
|
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
|
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
|
- pymdownx.highlight:
|
|
anchor_linenums: true
|
|
line_spans: __span
|
|
pygments_lang_class: true
|
|
- pymdownx.inlinehilite
|
|
- pymdownx.snippets:
|
|
base_path: .
|
|
url_download: true
|
|
dedent_subsections: true
|
|
- pymdownx.superfences:
|
|
custom_fences:
|
|
- name: mermaid
|
|
class: mermaid
|
|
format: !!python/name:pymdownx.superfences.fence_code_format
|
|
- pymdownx.tabbed:
|
|
alternate_style: true
|
|
slugify: !!python/object/apply:pymdownx.slugs.slugify
|
|
kwds:
|
|
case: lower
|
|
- toc:
|
|
permalink: true
|
|
|
|
# Plugins
|
|
plugins:
|
|
- search
|
|
- macros:
|
|
module_name: .mkdocs/macros
|
|
- redirects:
|
|
redirect_maps:
|
|
"specification/overview.md": "specification.md"
|
|
"specification/agent-card.md": "specification.md#5-agent-discovery-the-agent-card"
|
|
"specification/agent-to-agent-communication.md": "specification.md#6-protocol-data-objects"
|
|
"specification/sample-messages.md": "specification.md#9-common-workflows-examples"
|
|
"specification/details.md": "specification.md"
|
|
"documentation.md": "topics/key-concepts.md"
|
|
"resources.md": "index.md"
|
|
"topics/push-notifications.md": "topics/streaming-and-async.md"
|
|
"specification/topics/a2a_and_mcp.md": "topics/a2a-and-mcp.md"
|
|
"specification/topics/agent_discovery.md": "topics/agent-discovery.md"
|
|
"specification/topics/enterprise_ready.md": "topics/enterprise-ready.md"
|
|
"specification/topics/push_notification.md": "topics/streaming-and-async.md"
|
|
"specification/topics/push_notifications.md": "topics/streaming-and-async.md"
|
|
"topics/index.md": "topics/what-is-a2a.md"
|
|
"topics/roadmap.md": "roadmap.md"
|
|
# Tutorial
|
|
"tutorials/python/index.md": "tutorials/python/1-introduction.md"
|
|
"tutorials/python/1_introduction.md": "tutorials/python/1-introduction.md"
|
|
"tutorials/python/3-create-project.md": "tutorials/python/2-setup.md"
|
|
"tutorials/python/4-agent-skills.md": "tutorials/python/3-agent-skills-and-card.md"
|
|
"tutorials/python/5-add-agent-card.md": "tutorials/python/3-agent-skills-and-card.md"
|
|
"tutorials/python/6-start-server.md": "tutorials/python/5-start-server.md"
|
|
"tutorials/python/7-interact-with-server.md": "tutorials/python/6-interact-with-server.md"
|
|
"tutorials/python/8-agent-capabilities.md": "tutorials/python/7-streaming-and-multiturn.md"
|
|
"tutorials/python/9-ollama-agent.md": "tutorials/python/7-streaming-and-multiturn.md"
|
|
"tutorials/python/10-next-steps.md": "tutorials/python/8-next-steps.md"
|
|
"sdk/python/": "sdk/python/api/index.html"
|
|
- mike:
|
|
canonical_version: latest
|