Fix Sphinx build failure in Read the Docs due to myst-parser version incompatibility

[Copilot]

The Read the Docs build was failing with a ModuleNotFoundError: No module named 'myst_parser' error. This occurred because Read the Docs automatically upgrades Sphinx to version 8.2.3, but the project's myst-parser 3.0.1 only supports Sphinx versions >=6,<8, creating a version incompatibility.

Root Cause

Read the Docs runs these automatic steps during build:

python -m pip install --upgrade --no-cache-dir sphinx

This upgrades Sphinx to 8.2.3, but myst-parser 3.0.1 has the dependency constraint sphinx >=6,<8, making it incompatible with Sphinx 8.x.

Solution

Modified .readthedocs.yaml to use custom build commands instead of the automatic Sphinx installation. This ensures Poetry manages all dependencies with compatible versions:

Before:

• Read the Docs managed Sphinx installation (version 8.2.3)
• Automatic dependency conflicts with myst-parser

After:

• Poetry manages Sphinx 7.4.7 and myst-parser 3.0.1
• Custom build command: poetry run sphinx-build -T -b html -d _build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html

Changes

The key change is replacing the sphinx: configuration section with build.commands that give full control over the build process:

build:
  commands:
    - pip install poetry
    - poetry config virtualenvs.create false
    - poetry install --with docs
    - poetry run sphinx-build -T -b html -d _build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html

This ensures that Poetry's dependency resolution maintains version compatibility between all documentation tools.

Testing

• ✅ Local build works with Poetry-managed Sphinx 7.4.7
• ✅ myst-parser 3.0.1 imports and functions correctly
• ✅ Complete documentation generation succeeds
• ✅ Core tests pass (expected GitHub API rate limiting warnings)

Fixes #688.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• docs.micropython.org
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d _build/doctrees -D language=en docs test_output/html (dns block)
• docs.python.org
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d docs/_build/doctrees -D language=en docs docs/_build/html (dns block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d _build/doctrees -D language=en docs test_output/html (dns block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d _build/doctrees -D language=en docs final_test/html (dns block)
• https://api.github.com/repositories/15337142/tags
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d docs/_build/doctrees -D language=en docs docs/_build/html (http block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d _build/doctrees -D language=en docs test_build/html (http block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/pytest tests/rst/test_constants.py -v (http block)
• micropython-stubs.readthedocs.io
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d docs/_build/doctrees -D language=en docs docs/_build/html (dns block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d _build/doctrees -D language=en docs test_build/html (dns block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d _build/doctrees -D language=en docs test_output/html (dns block)
• www.sphinx-doc.org
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d _build/doctrees -D language=en docs test_output/html (dns block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/sphinx-build -T -b html -d _build/doctrees -D language=en docs final_test/html (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.58%. Comparing base (6dbb1a0) to head (7e9792a).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #689   +/-   ##
=======================================
  Coverage   78.58%   78.58%           
=======================================
  Files          70       70           
  Lines        6466     6466           
  Branches     1079     1079           
=======================================
  Hits         5081     5081           
  Misses       1034     1034           
  Partials      351      351           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.