Implementation:Microsoft Onnxruntime OnnxSphinx

Knowledge Sources	Microsoft_Onnxruntime
Domains	Documentation, Python, Sphinx
Last Updated	2026-02-10 04:00 GMT

Overview

A Sphinx extension that automatically generates RST documentation pages for all ONNX operators available in ONNX Runtime, including version diffs and operator examples.

Description

The `onnx_sphinx.py` module is a comprehensive Sphinx extension for generating ONNX operator documentation. It provides:

• Template system: Uses Jinja2 templates (with a fallback for environments without Jinja2) to render operator documentation in RST format. Three main templates:

 - `_template_operator`: Renders individual operator pages with version info, summary, attributes, inputs, outputs, type constraints, and examples.
 - `_template_diff`: Renders HTML diffs between operator versions using diff2html.
 - `_template_main`: Renders the index page with a tabbed layout organized by domain.

• Schema retrieval: `_populate__get_all_schemas_with_history` queries ONNX Runtime's `get_all_operator_schema` or `get_all_opkernel_def` to build a comprehensive schema registry organized by domain, operator name, and version. `get_operator_schemas` provides filtered access supporting specific versions, latest version, and domain filtering.

• Documentation generation: `get_rst_doc` is the core function that:

 - Retrieves operator schemas.
 - Processes documentation text (converting HTML tags, Markdown code blocks, and URLs to RST).
 - Renders attributes with default values, input/output specs with type constraints and options (optional, variadic, heterogeneous).
 - Optionally inserts version diffs between schema versions.
 - Optionally includes examples from `onnx.backend.test.case.node`.

• Version diffing: `_insert_diff` splits documentation at version boundaries, computes text diffs using Python's `difflib.Differ`, and renders interactive HTML diffs via the `diff2html` JavaScript library.

• Example extraction: `get_onnx_example` loads operator test cases from the onnx package, extracting `@staticmethod` methods from `_Exporter` classes and formatting them with necessary imports.

• Sphinx setup: The `setup(app)` function registers config values (`onnx_doc_folder`, `max_opsets`) and connects to the `builder-inited` event to trigger documentation generation.

• Utility functions: `change_style` converts CamelCase to snake_case, `is_last_schema` checks if a schema is the latest version, `_clean_unicode` normalizes HTML entities.

Usage

Add this extension to your Sphinx `conf.py` to automatically generate ONNX operator documentation for the ONNX Runtime build. Configure `onnx_doc_folder` and optionally `max_opsets` to control output.

Code Reference

Source Location

• Repository: Microsoft_Onnxruntime
• File: docs/python/_common/onnx_sphinx.py
• Lines: 1-899

Signature

def get_domain_list() -> list:
    """Returns the list of available domains."""

def get_operator_schemas(op_name, version=None, domain=None) -> list:
    """Returns all schemas mapped to an operator name."""

def get_rst_doc(folder, op_name=None, domain=None, version="last",
                clean=True, diff=False, example=False) -> tuple:
    """Returns documentation in RST format for OnnxOperator(s)."""

def onnx_documentation_folder(folder, title="ONNX Operators in onnxruntime",
                              flog=None, max_opsets=None) -> list:
    """Creates documentation in a folder for all known ONNX operators."""

def get_onnx_example(op_name) -> dict:
    """Retrieves examples associated to one operator from onnx packages."""

def is_last_schema(sch: OpSchema) -> bool:
    """Tells if this is the most recent schema for this operator."""

def change_style(name: str) -> str:
    """Switches from AaBb into aa_bb."""

def setup(app):
    """Sphinx extension entry point."""

Import

# In Sphinx conf.py:
extensions = ['docs.python._common.onnx_sphinx']
onnx_doc_folder = 'operators'
max_opsets = {}

I/O Contract

Function	Inputs	Outputs	Description
get_operator_schemas	op_name, version, domain	list of OpSchema	Retrieves operator schemas matching criteria
get_rst_doc	folder, op_name, domain, version, clean, diff, example	(RST string, links dict)	Generates RST documentation for operators
onnx_documentation_folder	folder, title, flog, max_opsets	list of file paths	Generates full documentation folder structure
get_onnx_example	op_name	dict of examples	Retrieves code examples from onnx test cases
setup	Sphinx app	extension metadata dict	Registers the Sphinx extension

Usage Examples

# Generate documentation programmatically
from docs.python._common.onnx_sphinx import onnx_documentation_folder

pages = onnx_documentation_folder(
    "output_docs",
    title="ONNX Operators",
    flog=print,
    max_opsets={"": 18, "ai.onnx.ml": 3}
)
print(f"Generated {len(pages)} documentation pages")

# Get docs for a specific operator
from docs.python._common.onnx_sphinx import get_rst_doc
doc, links = get_rst_doc("output_docs", op_name="Relu", version="last", example=True)

Related Pages

• Implementation:Microsoft_Onnxruntime_PlotCommonErrors
• Implementation:Microsoft_Onnxruntime_PlotMetadata
• Implementation:Microsoft_Onnxruntime_PlotPipeline