Implementation:NVIDIA DALI Sphinx Config

Knowledge Sources	NVIDIA_DALI
Domains	Documentation, Configuration
Last Updated	2026-02-08 16:00 GMT

Overview

Sphinx documentation configuration file that controls the generation of NVIDIA DALI's API reference and user guide, including version switching, auto-documentation of operators, and custom enum handling.

Description

This conf.py file is the central Sphinx configuration for building NVIDIA DALI's documentation. Beyond standard Sphinx settings, it performs substantial active work during the configuration phase: it reads the project version from a VERSION file, resolves the Git SHA for source linking, and dynamically generates operator documentation pages by invoking internal modules (operations_table, autodoc_submodules, doc_index, types_table) that introspect the DALI Python API to produce RST files for every operator's function and class variants, including both pipeline mode and dynamic mode APIs.

The configuration sets up a rich collection of Sphinx extensions including autodoc, Napoleon (for Google-style docstrings), nbsphinx (for Jupyter notebook integration), MathJax (configured for SVG rendering to work around Firefox rendering bugs), intersphinx, sphinx_paramlinks, and sphinx_design. It also constructs a comprehensive version switcher JSON file that covers every DALI release from 0.1 through the current version, with URL validation against the NVIDIA documentation archive. The NVIDIA Sphinx theme is preferred when available, with fallback to Read the Docs theme.

A notable feature is the custom EnumDocumenter and EnumAttributeDocumenter classes that handle pybind11 enum types that do not subclass Python's Enum. The setup() function registers these custom documenters along with a docstring post-processor (replace_params_with_paramrefs) that automatically converts parameter references in backticks to cross-referenced :paramref: links.

Usage

This file is consumed by Sphinx when building the DALI documentation. It is invoked via make html or sphinx-build from the docs/ directory. The configuration expects DALI to be installed or importable so that autodoc can introspect the Python API.

Code Reference

Source Location

• Repository: NVIDIA_DALI
• File: docs/conf.py
• Lines: 1-755

Signature

# Key configuration values
project = "NVIDIA DALI"
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.mathjax",
    "sphinx.ext.napoleon",
    "sphinx.ext.ifconfig",
    "sphinx.ext.extlinks",
    "IPython.sphinxext.ipython_console_highlighting",
    "nbsphinx",
    "sphinx.ext.intersphinx",
    "sphinx.ext.autosectionlabel",
    "sphinx_paramlinks",
    "sphinx_design",
    "dali_tabs",
]

# Custom autodoc classes
class EnumDocumenter(ClassDocumenter): ...
class EnumAttributeDocumenter(AttributeDocumenter): ...

# Docstring processing hooks
def replace_params_with_paramrefs(app, what, name, obj, options, lines): ...
def setup(app): ...

Import

# Build DALI documentation
cd docs/
sphinx-build -b html . _build/html
# or
make html

I/O Contract

Inputs

Name	Type	Required	Description
../VERSION	file	Yes	Project version file read to determine version_long and version_short
GIT_SHA	env var	No	Git commit hash for source links; auto-detected if not set
ADD_NVIDIA_VISITS_COUNTING_SCRIPT	env var	No	Analytics script URL for visitor counting
DALI Python API	importable module	Yes	nvidia.dali must be importable for autodoc introspection

Outputs

Name	Type	Description
_build/html/	directory	Complete HTML documentation site with API reference
operations/*.rst	files	Auto-generated operator documentation pages
_static/switcher.json	file	Version switcher JSON for the documentation theme

Usage Examples

Build HTML documentation

# Standard Sphinx build from docs directory
# conf.py is automatically loaded by Sphinx
import subprocess
subprocess.run(["sphinx-build", "-b", "html", "docs/", "docs/_build/html"])

Access version info programmatically

# Within conf.py, the following variables are available:
# version_long = "1.40.0"  (from VERSION file)
# version_short = "1.40"
# git_sha = "abc1234"
# version = "1.40.0-abc1234"
# release = "1.40.0"

Related Pages

• Environment:NVIDIA_DALI_CUDA_GPU_Environment