Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: Update Sphinx to 9.0.4 and numpydoc to >=1.10.0 #30725

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
ParamSingh24 wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

DOC: Update Sphinx to 9.0.4 and numpydoc to >=1.10.0 #30725

ParamSingh24 wants to merge 1 commit into from
+2 −2

Conversation

@ParamSingh24
Copy link

@ParamSingh24 ParamSingh24 commented Jan 25, 2026

Summary

Updates the pinned versions of Sphinx and Numpydoc in the documentation requirements to prevent the documentation build configuration from becoming outdated.

Closes #30684

Changes

File modified: requirements/doc_requirements.txt

  • Update Sphinx from 7.2.6 (2023) to 9.0.4 (2025)
  • Update numpydoc from ==1.10.0 to >=1.10.0

Rationale

Sphinx Update

  • Current version (7.2.6) is from 2023 and risks bitrot
  • Sphinx 9.0.4 is the latest version compatible with Python 3.11
  • Sphinx 9.1.0 (absolute latest) requires Python 3.12+, which NumPy doesn't yet require
  • This represents a 2 major version upgrade while maintaining compatibility

Numpydoc Update

  • Changed from pinned (==1.10.0) to minimum version (>=1.10.0)
  • Allows automatic updates to compatible patch versions
  • Reduces maintenance burden while ensuring minimum version requirements

Testing

  • All documentation dependencies install successfully without conflicts
  • Verified Sphinx 9.0.4 and Numpydoc 1.10.0 install correctly
  • No breaking changes in dependency tree
  • CI/CD (CircleCI) will verify documentation builds successfully

Notes

  • The CircleCI documentation build uses SPHINXOPTS="-W -n" (warnings as errors)
  • Some warnings may appear with the newer Sphinx version due to stricter validation
  • Any critical warnings will be addressed in follow-up PRs if needed
  • This change prevents the documentation tooling from becoming hopelessly outdated

Checklist

  • Commit message follows NumPy guidelines (starts with DOC:)
  • Changes are minimal and focused
  • No code changes, only dependency version updates
  • Ready for CI/CD testing

@ParamSingh24
DOC: Update Sphinx to 9.0.4 and numpydoc to >=1.10.0
b27b729 
- Update Sphinx from 7.2.6 (2023) to 9.0.4 (2025)
- Update numpydoc from ==1.10.0 to >=1.10.0
- Sphinx 9.1.0 requires Python 3.12+, so using 9.0.4 for Python 3.11 compatibility
- This prevents documentation build configuration from becoming outdated
@mattip
Copy link
Member

mattip commented Jan 25, 2026

Please run spin docs locally and fix the problems before iterating more on CI. This is not a simple change.

@ParamSingh24
Copy link
Author

ParamSingh24 commented Jan 26, 2026

Please run spin docs locally and fix the problems before iterating more on CI. This is not a simple change.

Sure I am addressing the issues , I see the CircleCI build and artifact generation are failing, which aligns with the local issues , I am moving to a local workflow now to debug the environment properly and will ensure all checks.

@melissawm
Copy link
Member

melissawm commented Jan 26, 2026

Sphinx 9.x includes an extensive rewrite of autodoc, which is the likely source of the errors here. You can try using the autodoc_use_legacy_class_based config option to see if that's sufficient to solve these issues.

@ngoldbaum ngoldbaum marked this pull request as draft January 28, 2026 16:11
@ngoldbaum
Copy link
Member

ngoldbaum commented Jan 28, 2026

I converted this to draft to indicate that this isn't ready to be merged yet.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

04 - Documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

DOC: update sphinx and numpydoc pins

4 participants

@ParamSingh24 @mattip @melissawm @ngoldbaum