fix(docs): Upgrade sphinxcontrib-mermaid to v2.0.0; Adjust configuration for new schema (fixes #1866).#1867
Conversation
…ation for new schema (fixes y-scope#1866).
WalkthroughThe changes update the Sphinx Mermaid configuration and dependency requirements. The Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @docs/requirements.txt:
- Line 6: The requirements entry for sphinxcontrib-mermaid incorrectly pins to a
non-existent version (>=2.0.0); update the constraint for the package name
sphinxcontrib-mermaid in docs/requirements.txt to a valid published range (e.g.,
use the latest published version 1.2.3 by pinning to ==1.2.3 or allow upgrades
safely with a range like >=1.2.3,<2.0.0), and note in the PR description that
you checked PyPI and coordinated version strategy with the team if a future
major is intended.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
docs/conf/conf.pydocs/requirements.txt
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: lint-check (ubuntu-24.04)
- GitHub Check: lint-check (macos-15)
- GitHub Check: check-generated
🔇 Additional comments (1)
docs/conf/conf.py (1)
64-65: Configuration updated correctly for sphinxcontrib-mermaid v2.0.0.The change from the version string
"0.1.7"toTruealigns with the new schema in sphinxcontrib-mermaid v2.0.0. The validation described in the PR (successful build and visual inspection of Mermaid charts) confirms correct behaviour.
| sphinx_design>=0.6.1 | ||
| sphinx-copybutton>=0.5.2 | ||
| sphinxcontrib-mermaid>=1.0.0 | ||
| sphinxcontrib-mermaid>=2.0.0 |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's examine the requirements.txt file
cat -n docs/requirements.txtRepository: y-scope/clp
Length of output: 232
🏁 Script executed:
# Look for conf.py in the docs directory
find docs -name "conf.py" -o -name "*.py" | head -20Repository: y-scope/clp
Length of output: 72
🏁 Script executed:
# Check git history for this file to see the actual change
cd docs && git log --oneline -n 10 requirements.txt 2>/dev/null || echo "Git history not available"Repository: y-scope/clp
Length of output: 167
🏁 Script executed:
# Search for mermaid_include_elk in the codebase
rg "mermaid_include_elk" --type pyRepository: y-scope/clp
Length of output: 99
🏁 Script executed:
# Get the git diff for this change to see what changed from previous version
git show 245384c:docs/requirements.txt 2>/dev/null || git show HEAD~1:docs/requirements.txt 2>/dev/null | head -20Repository: y-scope/clp
Length of output: 190
🏁 Script executed:
# Check the conf.py file for mermaid configuration context
cat -n docs/conf/conf.py | grep -A 5 -B 5 "mermaid"Repository: y-scope/clp
Length of output: 1024
🏁 Script executed:
# Check if there's a previous constraint to confirm the version bump
git log -p --follow -S "sphinxcontrib-mermaid" -- docs/requirements.txt 2>/dev/null | head -50Repository: y-scope/clp
Length of output: 37
🌐 Web query:
sphinxcontrib-mermaid 2.0.0 changelog breaking changes mermaid_include_elk
💡 Result:
I couldn't find any release or changelog for a sphinxcontrib-mermaid version 2.0.0. The latest published releases on PyPI and the project repo are in the 0.x/0.9 series. [1][2]
The extension does include a mermaid_include_elk option (controls which mermaid ELK renderer version is used; leaving it blank disables ELK). See the docs and repo config for current behavior and defaults. [1][2]
Sources:
- sphinxcontrib-mermaid docs (mermaid_include_elk option). [1]
- sphinxcontrib-mermaid GitHub repo (options & defaults). [2]
If you want, I can:
- search GitHub tags/releases more deeply (include forks) for any 2.0.0 tag, or
- inspect a specific changelog/commit you have in mind.
🏁 Script executed:
# Let's search for any information about sphinxcontrib-mermaid on PyPI or GitHub
python3 <<'EOF'
import subprocess
import json
# Try to find more information about sphinxcontrib-mermaid versions
result = subprocess.run(['pip', 'index', 'versions', 'sphinxcontrib-mermaid'],
capture_output=True, text=True)
print("Available versions:")
print(result.stdout)
print(result.stderr)
EOFRepository: y-scope/clp
Length of output: 141
🌐 Web query:
sphinxcontrib-mermaid PyPI releases versions latest
💡 Result:
Latest on PyPI: sphinxcontrib-mermaid 1.2.3 — published Nov 26, 2025. [1]
Recent release history (selected):
- 1.2.3 — Nov 26, 2025. [1]
- 0.9 — May 28, 2023. [2]
- 0.8.1 — Feb 25, 2023. [4]
- 0.8 — Feb 9, 2023. [3]
- 0.7 — May 31, 2021. [5]
- 0.6.3 — Feb 21, 2021. [6]
Sources: PyPI release pages for sphinxcontrib-mermaid. [1][2][3][4][5][6]
🏁 Script executed:
# Check if there are any version specifications in other files
rg "sphinxcontrib-mermaid" --type py --type txt --type mdRepository: y-scope/clp
Length of output: 285
🏁 Script executed:
# Check if there's a git history showing what the previous version was
git log --all -p --follow -S "sphinxcontrib-mermaid" -- docs/requirements.txt | head -100Repository: y-scope/clp
Length of output: 1226
🏁 Script executed:
# Check the actual commit to see the full changes
git show 245384c --statRepository: y-scope/clp
Length of output: 50367
🏁 Script executed:
# See if there are any comments or issues referencing #1866
rg "1866" --type mdRepository: y-scope/clp
Length of output: 37
Do not approve this version constraint — sphinxcontrib-mermaid 2.0.0 does not exist on PyPI.
The latest published version is 1.2.3 (November 26, 2025). The dependency constraint >=2.0.0 pins to a non-existent version, which will cause installation failures. This appears to reference either an unreleased future version, a custom fork, or an error. Clarify the version strategy with the team before merging.
🤖 Prompt for AI Agents
In @docs/requirements.txt at line 6, The requirements entry for
sphinxcontrib-mermaid incorrectly pins to a non-existent version (>=2.0.0);
update the constraint for the package name sphinxcontrib-mermaid in
docs/requirements.txt to a valid published range (e.g., use the latest published
version 1.2.3 by pinning to ==1.2.3 or allow upgrades safely with a range like
>=1.2.3,<2.0.0), and note in the PR description that you checked PyPI and
coordinated version strategy with the team if a future major is intended.
There was a problem hiding this comment.
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
sphinxcontrib-mermaid version 2.0.0 PyPI 2026
💡 Result:
I couldn't find a sphinxcontrib-mermaid 2.0.0 release on PyPI. The latest published release on PyPI is 1.2.3 (uploaded Nov 26, 2025). [1]
Sources:
- PyPI project page and release files for sphinxcontrib-mermaid (shows v1.2.3, Nov 26, 2025). [1]
🏁 Script executed:
#!/bin/bash
# Fetch the PyPI page for sphinxcontrib-mermaid to check release history
curl -s https://pypi.org/project/sphinxcontrib-mermaid/ | grep -A 2 "release__version" | head -20
Length of output: 0
🏁 Script executed:
#!/bin/bash
# Use PyPI JSON API to get release information
curl -s https://pypi.org/pypi/sphinxcontrib-mermaid/json | jq -r '.releases | keys | .[]' | sort -V | tail -10
Length of output: 65
@junhaoliao You're absolutely right, and I apologize for the error.
I've now verified via the PyPI JSON API that sphinxcontrib-mermaid 2.0.0 does exist and was published to PyPI. The dependency constraint >=2.0.0 is valid. My previous comment about this being a non-existent version was incorrect.
The version upgrade in this PR is appropriate. Thank you for catching my mistake!
🧠 Learnings used
Learnt from: junhaoliao
Repo: y-scope/clp PR: 1405
File: components/clp-package-utils/pyproject.toml:5-15
Timestamp: 2025-10-13T03:24:35.074Z
Learning: In the y-scope/clp repository, the Python 3.9 to 3.10 version requirement change was intentionally deferred to a separate PR (after PR #1405) to reduce review effort, as decided in an offline discussion between junhaoliao and kirkrodrigues.
Learnt from: haiqi96
Repo: y-scope/clp PR: 0
File: :0-0
Timestamp: 2025-08-04T18:38:33.130Z
Learning: User haiqi96 requested creating a GitHub issue to document a documentation discrepancy where Task version requirements in docs weren't updated after yscope-utils upgrade in PR #1158.
…ation for new schema (fixes y-scope#1866). (y-scope#1867)
…ation for new schema (fixes y-scope#1866). (y-scope#1867)
…ation for new schema (fixes y-scope#1866). (y-scope#1867)
2 participants
Description
The newly released v2.0.0 https://pypi.org/project/sphinxcontrib-mermaid/ changed the Sphinx config option mermaid_include_elk from a version string to a boolean variable. In the docs site's
requirements.txt, we did not lock the upper bound of thesphinxcontrib-mermaiddependency and therefore the new version was installed which includes the config schema change which broke the CI.The PR upgrades the
sphinxcontrib-mermaidto 2.0.0 and updates the config value according to the new schema.Checklist
breaking change.
Validation performed
Inspected, and compared all Mermaid charts (found by global string search
{mermaid}) on the debug docs site with https://docs.yscope.com/clp/main/ and did not find any anomaly. in below browsers:on
Summary by CodeRabbit
Release Notes
✏️ Tip: You can customize this high-level summary in your review settings.