Principle:Openai Openai agents python Documentation Build Pipeline
| Knowledge Sources | |
|---|---|
| Domains | Documentation, Build_Tooling |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
System of scripts and configuration that builds, translates, and publishes the SDK documentation site in multiple languages.
Description
The Documentation Build Pipeline encompasses the toolchain used to produce the OpenAI Agents SDK documentation website. It consists of three key components: (1) an MkDocs Material configuration (`mkdocs.yml`) that defines the site structure, plugins (mkdocstrings for API reference generation, i18n for multi-language support), navigation, theme, and markdown extensions; (2) a translation script (`translate_docs.py`) that uses the OpenAI API to translate English documentation into Japanese, Korean, and Chinese with domain-specific terminology control; and (3) the example runner (`run_examples.py`) that validates example code continues to work.
The translation pipeline uses chunking to split documents at section boundaries while preserving code blocks untranslated (replaced with placeholders). It supports incremental translation by comparing git timestamps of source and target files, and runs translations concurrently using ThreadPoolExecutor. The MkDocs configuration defines per-locale navigation trees and integrates mkdocstrings for auto-generated API reference pages.
Usage
This principle applies when contributing to, maintaining, or understanding the SDK documentation infrastructure. The MkDocs configuration controls which pages appear in navigation and how API docs are generated. The translation script controls how documentation reaches non-English audiences. The example runner validates that code examples remain functional.
Theoretical Basis
The documentation pipeline follows a multi-stage content pipeline pattern:
Pseudo-code Logic:
# Abstract documentation pipeline
for each source_doc in english_docs:
# Stage 1: Author in English (manual)
# Stage 2: Translate to target languages
for lang in [ja, ko, zh]:
if is_stale(source_doc, lang):
chunks = split_preserving_code_blocks(source_doc)
translated = [translate(chunk, lang) for chunk in chunks]
restore_code_blocks(translated)
write(target_path / lang / source_doc)
# Stage 3: Build site
mkdocs_build() # generates HTML from md + API docstrings