Skip to content

chore: upgrade docs build toolchain and fix RTD build - #55

Merged
magajh merged 5 commits into
mainfrom
maga/fix-read-the-docs-action
Aug 20, 2026
Merged

chore: upgrade docs build toolchain and fix RTD build#55
magajh merged 5 commits into
mainfrom
maga/fix-read-the-docs-action

Conversation

@magajh

@magajh magajh commented May 12, 2026

Copy link
Copy Markdown
Contributor

What this PR does:

Fixes a broken Read the Docs build caused by an outdated pinned Sphinx version, modernizes the documentation toolchain, and updates conf.py to be compatible with the upgraded dependencies.

Changes:

  • Upgrades .readthedocs.yml to use ubuntu-24.04 and Python 3.12
  • Unpins all documentation requirements, letting pip resolve the latest compatible versions
  • Removes unnecessary internal Sphinx dependencies from requirements
  • Updates html_sidebars in conf.pysidebar-logo.html renamed to navbar-logo.html in sphinx-book-theme 1.x
  • Removes unsupported logo_only and extra_navbar theme options from conf.py
  • Upgrades requirements/pip-tools.txt (dev tooling only, no runtime impact)

Root cause of the broken build:

sphinx==4.2.0 depends on pkg_resources (from setuptools), which is no longer available by default in modern Python environments. Upgrading Sphinx removes this dependency entirely.

@magajh magajh changed the title chore: upgrade requirements chore: unpin docs requirements and upgrade build toolchain May 12, 2026
@magajh
magajh marked this pull request as ready for review May 13, 2026 04:10
@magajh
magajh requested a review from a team as a code owner May 13, 2026 04:10
@magajh magajh changed the title chore: unpin docs requirements and upgrade build toolchain chore: upgrade docs build toolchain and fix RTD build May 13, 2026

@MaferMazu MaferMazu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good to me ✅

Nit: I suggest adding a newline at the end of the doc.in file.

@magajh

magajh commented Aug 20, 2026

Copy link
Copy Markdown
Contributor Author

@MaferMazu thanks for the review!

I've added the new line at the end of doc.in, so I think we are ready to merge

@magajh
magajh force-pushed the maga/fix-read-the-docs-action branch from a1394bc to caad4e1 Compare August 20, 2026 17:45
@magajh
magajh merged commit 6916e4c into main Aug 20, 2026
1 check was pending
@magajh
magajh deleted the maga/fix-read-the-docs-action branch August 20, 2026 17:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants