A2A/mkdocs.yml
Darrel 18ca2533bf
docs(spec): Updated specification to render data models as a table generated from the proto instead of a raw proto snippet (#1225)
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>
2025-11-25 09:11:28 -08:00

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