Implementation:Onnx Onnx Gen Doc
| Knowledge Sources | |
|---|---|
| Domains | Documentation Generation, Operator Schema, Code Generation |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
gen_doc.py is a Python script that automatically generates Markdown documentation for all ONNX operator schemas, producing both the operator reference pages and changelog files used in official ONNX documentation.
Description
This script is the primary documentation generation tool for the ONNX operator ecosystem. It iterates through all registered operator schemas (retrieved via defs.get_all_schemas_with_history()) and formats them into structured Markdown documentation. The output includes two types of documentation files:
Changelog files (e.g., Changelog.md, Changelog-ml.md) organize operators by domain and version, providing a historical view of when each operator was introduced or modified. Each entry includes the operator name with version anchors, documentation text, attributes, inputs, outputs, and type constraints.
Operator schema files (e.g., Operators.md, Operators-ml.md) present the current state of all operators with a table of contents, support level indicators, version links, and detailed schema documentation. They also include code snippets from test cases and sample implementations when available.
The script handles domain-specific filtering (separating standard ONNX operators from ONNX-ML operators based on the ONNX_ML environment variable), supports deprecated operator marking, formats variadic and optional parameter tags with differentiability annotations, and renders attribute types with default values.
Usage
This script is invoked as part of the ONNX documentation build process. It should be run whenever operator definitions change to keep documentation synchronized with the schema definitions. The script reads from the onnx/defs directory and writes to the docs/ directory. It is typically run from the repository root and controlled by the ONNX_ML environment variable for domain selection.
Code Reference
Source Location
- Repository: Onnx_Onnx
- File: onnx/defs/gen_doc.py
- Lines: 1-440
Signature
def main(args: Args) -> None
def display_schema(schema: OpSchema, versions: Sequence[OpSchema], changelog: str) -> str
def display_number(v: int) -> str
def should_render_domain(domain: str, output: str) -> bool
def format_name_with_domain(domain: str, schema_name: str) -> str
def format_versions(versions: Sequence[OpSchema], changelog: str) -> str
def display_attr_type(v: OpSchema.AttrType) -> str
def display_domain(domain: str) -> str
def display_domain_short(domain: str) -> str
def generate_formal_parameter_tags(formal_parameter: OpSchema.FormalParameter) -> str
def support_level_str(level: OpSchema.SupportType) -> str
Import
from onnx.defs.gen_doc import main, display_schema
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| args | Args (NamedTuple) | Yes | Contains output (filename for operator schema docs, e.g., "Operators.md") and changelog (filename for changelog docs, e.g., "Changelog.md") |
| ONNX_ML | Environment Variable | No | When set to "0", disables ML domain documentation generation. Defaults to enabled. |
Outputs
| Name | Type | Description |
|---|---|---|
| Operators.md | File | Generated Markdown file containing all standard ONNX operator schemas with table of contents, version links, attributes, inputs, outputs, type constraints, and examples |
| Changelog.md | File | Generated Markdown file containing the version history of all standard ONNX operators organized by domain and version |
| Operators-ml.md | File | Generated Markdown file for ONNX-ML domain operators (when ONNX_ML is enabled) |
| Changelog-ml.md | File | Generated Markdown changelog for ONNX-ML domain operators (when ONNX_ML is enabled) |
Usage Examples
# Run from command line to generate all documentation
# With ML domain support (default):
python onnx/defs/gen_doc.py
# Without ML domain:
ONNX_ML=0 python onnx/defs/gen_doc.py
# Programmatic usage:
from onnx.defs.gen_doc import main, Args
# Generate standard ONNX operator docs
main(Args("Operators.md", "Changelog.md"))
# Generate ML domain operator docs
main(Args("Operators-ml.md", "Changelog-ml.md"))
# Use display_schema to format a single operator
from onnx import defs
from onnx.defs.gen_doc import display_schema
schema = defs.get_schema("Add", 13)
versions = [schema]
doc_str = display_schema(schema, versions, "Changelog.md")