mscclpp/docs/conf.py

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html


# -- Path setup --------------------------------------------------------------
import sys
import importlib.util
from pathlib import Path
from unittest.mock import MagicMock


class NamedMock(MagicMock):
    def __getattr__(self, name):
        attr = super().__getattr__(name)
        if isinstance(attr, MagicMock):
            # Assigns __name__ and __qualname__ to satisfy Sphinx autodoc inspection.
            attr.__name__ = name
            attr.__qualname__ = name
        return attr


# Add the python package to sys.path so Sphinx can find it
project_root = Path(__file__).parent.parent
python_path = project_root / "python"
sys.path.insert(0, str(python_path))

# -- Project version -----------------------------------------------------
spec = importlib.util.spec_from_file_location("_version", python_path / "mscclpp" / "_version.py")
version_module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(version_module)
version = version_module.__version__

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "mscclpp"
copyright = "2025, MSCCL++ Team"
author = "MSCCL++ Team"
release = "v" + version

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    "breathe",
    "myst_parser",
    "sphinxcontrib.mermaid",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
    "sphinx_autodoc_typehints",
    "sphinx_multiversion",
]

# sphinx-multiversion configuration
# Only build tagged versions - main branch is built separately via sphinx-build
# to avoid issues with config loading during ref checkout
smv_tag_whitelist = r"^v\d+\.\d+\.\d+$"
smv_branch_whitelist = r"^$"  # Don't build any branches, only tags
smv_remote_whitelist = None
smv_released_pattern = r"^tags/.*$"
smv_outputdir_format = "{ref.name}"
smv_prefer_remote_refs = False

autosummary_generate = True
autodoc_default_options = {
    "members": True,
    "inherited-members": True,
    "show-inheritance": True,
}
# only mock the C-extension when using the source tree
autodoc_mock_imports = ["mscclpp._version", "blake3", "cupy", "mpi4py", "numpy", "sortedcontainers"]
autodoc_typehints = "description"
napoleon_google_docstring = True
napoleon_numpy_docstring = True
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
}
mock_mscclpp = NamedMock()
# Set attributes to satisfy Sphinx autodoc inspection.
mock_mscclpp.env.return_value.cache_dir = "_mscclpp"
sys.modules["mscclpp._mscclpp"] = mock_mscclpp

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

# Breathe configuration
breathe_projects = {"mscclpp": "./doxygen/xml"}
breathe_default_project = "mscclpp"

# Mermaid configuration
mermaid_version = "11.0.0"
mermaid_init_js = "mermaid.initialize({startOnLoad:true});"

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]

# Build html_js_files dynamically - only include files that exist
# versions.js is auto-generated by generate_versions.py before build
html_js_files = []
_static_dir = Path(__file__).parent / "_static"
if (_static_dir / "versions.js").exists():
    html_js_files.append("versions.js")
if (_static_dir / "version-selector.js").exists():
    html_js_files.append("version-selector.js")


def setup(app):
    """Set up custom Sphinx build hooks for sphinx-multiversion support.

    This function registers a build-finished event handler that copies the
    version selector JavaScript files to a shared location accessible by all
    versioned documentation builds.

    Args:
        app: The Sphinx application instance.
    """
    import shutil

    def copy_version_files(app, exception):
        """Copy version JS files to the root build directory after a successful build.

        When using sphinx-multiversion, each version's documentation is built into
        its own subdirectory (e.g., _build/html/v0.8.0/). The version selector
        JavaScript files need to be available at the root _static directory
        (_build/html/_static/) so they can be shared across all versions and
        properly navigate between different documentation versions.

        Args:
            app: The Sphinx application instance.
            exception: Exception raised during build, or None if build succeeded.
        """
        if exception is None:  # Only copy if build succeeded
            source_static = Path(app.srcdir) / "_static"
            dest_root = Path(app.outdir).parent / "_static"
            dest_root.mkdir(parents=True, exist_ok=True)

            # Copy both versions.js and version-selector.js
            for filename in ["versions.js", "version-selector.js"]:
                source = source_static / filename
                if source.exists():
                    shutil.copy2(source, dest_root / filename)

    app.connect("build-finished", copy_version_files)