Implementation:Ray project Ray Sphinx Configuration

Knowledge Sources	Ray
Domains	Documentation, Build_System, Configuration
Last Updated	2026-02-13

Overview

Sphinx Configuration is the main Sphinx conf.py file that controls the entire documentation build pipeline for the Ray project, defining all extensions, theme settings, autodoc configuration, and custom build hooks.

Description

This configuration file (conf.py) sets up a comprehensive Sphinx documentation build environment for Ray. It registers over 20 Sphinx extensions including autodoc, MyST-NB, Napoleon, intersphinx, sphinx-design, sphinx_docsearch (Algolia), and custom extensions like callouts and queryparamrefs. The file configures the pydata-sphinx-theme with custom navbar components, version switching, and custom CSS/JS assets, mocks out heavy ML library imports (TensorFlow, PyTorch, NumPy, etc.) to allow documentation builds without installing all dependencies, and defines API grouping/filtering logic through custom Jinja2 filters. It also integrates with ReadTheDocs for version JSON generation, sets up link checking with extensive ignore patterns, and registers Sphinx event hooks for ecosystem doc downloading, link check summarization, and example gallery pre-generation.

Usage

This file is automatically loaded by Sphinx when building the Ray documentation. Modify it when adding new Sphinx extensions, changing theme settings, updating mocked imports, adjusting link check behavior, or modifying the documentation build pipeline. The DOC_LIB and RUN_NOTEBOOKS environment variables can be used to customize build behavior.

Code Reference

Source Location

doc/source/conf.py

Signature

# Key configuration values
project = "Ray"
html_theme = "pydata_sphinx_theme"
default_role = "code"
master_doc = "index"
language = "en"
nitpicky = True

extensions = [
    "callouts",
    "queryparamrefs",
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx.ext.napoleon",
    "sphinx_click.ext",
    "sphinx-jsonschema",
    "sphinxemoji.sphinxemoji",
    "sphinx_copybutton",
    "sphinx_sitemap",
    "myst_nb",
    "sphinx.ext.doctest",
    "sphinx.ext.coverage",
    "sphinx.ext.autosummary",
    "sphinxcontrib.autodoc_pydantic",
    "sphinxcontrib.redoc",
    "sphinx_remove_toctrees",
    "sphinx_design",
    "sphinx.ext.intersphinx",
    "sphinx_docsearch",
]

def setup(app):
    """Register all custom hooks and event handlers."""
    ...

Import

from custom_directives import (
    DownloadAndPreprocessEcosystemDocs,
    update_context,
    LinkcheckSummarizer,
    parse_navbar_config,
    setup_context,
    pregenerate_example_rsts,
    generate_versions_json,
    collect_example_orphans,
)

I/O Contract

Inputs

Input	Type	Description
Environment: DOC_LIB	str	If set, builds only the specified top-level documentation section
Environment: RUN_NOTEBOOKS	str	Controls notebook execution mode: "off", "force", or "cache"
Environment: READTHEDOCS	str	Set to "True" when building on ReadTheDocs
Environment: READTHEDOCS_VERSION	str	Current version being built on ReadTheDocs
Environment: LINKCHECK_ALL	str	If set, checks all external links rather than just ray-project links
navbar.yml	YAML file	Navigation bar configuration defining site navigation structure
_templates/	directory	Jinja2 templates for page rendering
_static/	directory	Static assets including CSS, JS, images, and favicon

Outputs

Output	Type	Description
HTML documentation	directory	Complete rendered HTML documentation site for docs.ray.io
LaTeX documentation	.tex file	LaTeX output (Ray.tex)
Man pages	man file	Unix manual page for Ray
versions.json	JSON file	Version switcher data for ReadTheDocs builds
Auto-generated API docs	.rst files	Public API documentation generated via autosummary

Usage Examples

Building the documentation locally:

cd doc/source
make html

Building only a specific library section:

DOC_LIB=tune make html

Enabling notebook execution during build:

RUN_NOTEBOOKS=cache make html

Key classes defined in the configuration:

class MockVersion(Version):
    """Patches packaging.version.Version to handle non-string inputs."""
    def __init__(self, version: str):
        if isinstance(version, (str, bytes)):
            super().__init__(version)
        else:
            super().__init__("0")

class MockedClassDocumenter(autodoc.ClassDocumenter):
    """Remove 'Bases: object' note from autodoc output."""
    def add_line(self, line: str, source: str, *lineno: int) -> None:
        if line == "   Bases: :py:class:`object`":
            return
        super().add_line(line, source, *lineno)

class DuplicateObjectFilter(logging.Filter):
    """Filter out expected duplicate object warnings."""
    def filter(self, record):
        if "duplicate object description of ray.actor.ActorMethod.bind" in record.getMessage():
            return False
        return True

Related Pages

• Ray_project_Ray_Custom_Sphinx_Directives - Custom Sphinx directives and build hooks imported by this configuration
• Ray_project_Ray_Sphinx_Callouts_Extension - Custom callout extension loaded as an extension
• Ray_project_Ray_PyTorch_Hyperparameter_Tuning_Tutorial - Example tutorial built by this documentation pipeline
• Ray - Ray project repository