Implementation:Onnx Onnx Onnx Sphinx Extension

Knowledge Sources	Onnx_Onnx
Domains	Documentation, Sphinx Extension, Code Generation
Last Updated	2026-02-10 00:00 GMT

Overview

Custom Sphinx extension that automatically generates operator documentation pages for all ONNX operators, including version history, visual diffs, and code examples extracted from the test suite.

Description

The onnx_sphinx module is a Sphinx extension that automates the generation of the entire ONNX operator reference section. It registers with Sphinx via the setup(app) function, hooking into the builder-inited event to trigger documentation generation before the build begins.

The core function onnx_documentation_folder iterates over all ONNX operator schemas retrieved from onnx.defs.get_all_schemas_with_history(), grouped by domain (e.g., ai.onnx, ai.onnx.ml). For each operator, it renders a Jinja2 template (_template_operator) that produces Markdown documentation including version information, summary text, attributes, inputs, outputs, type constraints, and inline code examples. A separate _template_main generates the index page with tabbed navigation across domains.

The get_onnx_example function dynamically imports test case modules from onnx.backend.test.case.node and extracts example code using inspect.getsource. It handles PascalCase-to-snake_case conversion of operator names for module lookup. The _insert_diff function generates HTML-based visual diffs between operator versions using difflib.Differ and the diff2html JavaScript library, rendering them as embedded HTML in the documentation pages.

A secondary function _copy_repo_docs copies repository-level Markdown documentation files into the Sphinx source tree, excluding blocklisted files like Changelog.md, Operators.md, and other generated files specified in the REPO_DOCS_EXCLUDE set.

The module also provides helper functions for text processing: pascal_to_snake_case for name conversion, _clean_unicode for character entity replacement, and various inner functions within get_markdown_doc for formatting operator schema data (type constraints, default values, function bodies, etc.).

Usage

This extension is activated by adding 'onnx_sphinx' to the extensions list in the Sphinx conf.py configuration file. It accepts three configuration values: onnx_doc_folder (default: "operators"), onnx_md_folder (default: "repo-docs"), and max_opsets (default: empty dict). Documentation is generated automatically during the Sphinx build process. A debug mode is available by running the module directly with "debug" as a command-line argument.

Code Reference

Source Location

• Repository: Onnx_Onnx
• File: docs/docsgen/source/onnx_sphinx.py
• Lines: 1-905

Signature

def setup(app):
    """Sphinx extension `onnx_sphinx` displays documentation on ONNX Operators."""

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

def get_markdown_doc(folder, op_name=None, domain=None, version="last",
                     clean=True, diff=False, example=False):
    """Returns a documentation in Markdown format for all OnnxOperator."""

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

def get_onnx_example(op_name, domain):
    """Retrieves examples associated to one operator stored in onnx packages."""

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

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

Import

from docs.docsgen.source.onnx_sphinx import (
    setup,
    get_operator_schemas,
    get_markdown_doc,
    onnx_documentation_folder,
    get_onnx_example,
    is_last_schema,
    pascal_to_snake_case,
)

I/O Contract

Inputs

Name	Type	Required	Description
app	sphinx.application.Sphinx	Yes	Sphinx application instance (for setup())
folder	str	Yes	Output folder path for generated documentation
op_name	str	No	Specific operator name to generate docs for; None for all operators
domain	str	No	Operator domain filter (e.g., "ai.onnx.ml")
version	str/int/None	No	Version filter; "last" for most recent, None for all versions
max_opsets	dict	No	Dictionary mapping domains to maximum opset version to include

Outputs

Name	Type	Description
pages	list[str]	List of file paths for all generated documentation pages
docs	str	Rendered Markdown documentation string (from get_markdown_doc)
d_links	dict	Dictionary mapping version numbers and version pairs to reference links
n_examples	int	Count of examples found for the operator

Usage Examples

# In Sphinx conf.py
extensions = ['onnx_sphinx']
onnx_doc_folder = "operators"
onnx_md_folder = "repo-docs"
max_opsets = {}

# Direct usage for generating documentation
from docs.docsgen.source.onnx_sphinx import onnx_documentation_folder
pages = onnx_documentation_folder("output_dir", flog=print)

# Get documentation for a specific operator
from docs.docsgen.source.onnx_sphinx import get_markdown_doc
docs, links, n_examples = get_markdown_doc(
    "output_dir", "Relu", domain="", version="last", example=True, diff=True
)

# Get schemas for an operator
from docs.docsgen.source.onnx_sphinx import get_operator_schemas
schemas = get_operator_schemas("Conv", version="last", domain="")

Related Pages

• sphinx - Sphinx documentation framework
• jinja2 - Template engine for rendering operator docs
• numpy - Used for formatting default attribute values
• difflib - Generates text diffs between operator versions
• onnx.defs.OpSchema - Operator schema definitions consumed by this extension
• onnx.backend.test.case.base._Exporter - Test case exporter providing code examples