Pins Sphinx <8 for sphinx-multiversion compatibility

[kellyguo11]

Description

Fixes the docs build failure that started on April 8-9, causing develop and release/3.0.0-beta to disappear from the published docs.

Root Cause

sphinx-multiversion==0.2.4 is not compatible with Sphinx 8.x due to changes in the Config.read() signature. The build was failing with:

TypeError: Config.read() takes 2 positional arguments but 3 were given

This happened because sphinx>=7.0,<9 allowed Sphinx 8.x to be installed.

Fix

Pin Sphinx to <8 until sphinx-multiversion is updated or replaced with a compatible alternative.

Type of change

• Bug fix (non-breaking change which fixes an issue)

Checklist

• I have read and understood the contribution guidelines

[greptile-apps]

Greptile Summary

Tightens the Sphinx upper bound from <9 to <8 in docs/requirements.txt to prevent installation of Sphinx 8.x, which broke sphinx-multiversion==0.2.4 with a TypeError: Config.read() takes 2 positional arguments but 3 were given. The inline comment clearly documents the reason for the constraint.

Confidence Score: 5/5

Safe to merge — single-line constraint tightening with a clear explanation, directly fixes the documented build failure.

The change is minimal and correct: tightening <9 to <8 prevents Sphinx 8.x from being pulled in and resolves the known incompatibility. The inline comment documents the reason. No source code is touched, no changelog entry is required for docs infrastructure changes, and there are no other issues.

No files require special attention.

Important Files Changed

Filename	Overview
docs/requirements.txt	Pins Sphinx to <8 (from <9) with an inline comment explaining the sphinx-multiversion incompatibility; minimal, targeted fix.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[docs build triggered] --> B{Sphinx version installed?}
    B -->|">=7.0, <9 (before)"| C[Sphinx 8.x may be installed]
    B -->|">=7.0, <8 (after fix)"| D[Sphinx 7.x installed]
    C --> E["sphinx-multiversion calls Config.read(app, config_dir, overrides)"]
    D --> F["sphinx-multiversion calls Config.read(app, config_dir, overrides)"]
    E --> G["TypeError: Config.read() takes 2 positional args but 3 given"]
    F --> H[Docs build succeeds]
    G --> I[Build fails — docs disappear from site]

Loading

_{Reviews (2): Last reviewed commit: "fix(docs): pin Sphinx <8 for sphinx-mult..." | Re-trigger Greptile}

[AntoineRichard]

@kellyguo11 I think the previous PR was correct, but it was not targeting the right branch. It should have targeted main since it's main that's building the doc. I'm closing this PR, and opening a new one to main that pins Sphinx to 7<x<9. (#5223)

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

One-line docs dependency pin: narrows Sphinx from >=7.0,<9 to >=7.0,<8 to fix sphinx-multiversion 0.2.4 incompatibility with Sphinx 8.x. The root cause (Config.read() signature change) and the fix are clearly documented in both the PR description and the inline comment.

Design Assessment

Design is sound. Pinning the upper bound is the correct minimal fix. sphinx-multiversion==0.2.4 is already pinned in the same file, confirming the dependency. The inline comment makes the constraint reason discoverable for future maintainers.

Findings

No issues found. The change is a single version-specifier tightening with no runtime impact.

Test Coverage

No new tests needed — this is a docs build dependency change with no runtime code impact. CI's "Build Latest Docs" and "Check for Broken Links" pipelines are the appropriate validation.

CI Status

• ✅ pre-commit, labeler, Detect Doc Build Type, Check for Broken Links — passing
• ⏳ Build Latest Docs, license-check — pending (expected to pass with the fix)
• ⏭️ Build Multi-Version Docs, Deploy Docs — skipping (likely gated on latest docs build)

Verdict

Ship it — Correct, minimal fix for a real docs build breakage. Well-documented root cause.