Skip to content

docs: configure Sphinx directly and drop unmaintained sphinx-pyproject - #15123

Closed
priya-sundaram-dev wants to merge 1 commit into
TheAlgorithms:masterfrom
priya-sundaram-dev:sphinx-direct
Closed

docs: configure Sphinx directly and drop unmaintained sphinx-pyproject#15123
priya-sundaram-dev wants to merge 1 commit into
TheAlgorithms:masterfrom
priya-sundaram-dev:sphinx-direct

Conversation

@priya-sundaram-dev

Copy link
Copy Markdown
Contributor

Describe your change:

Follow-up to #15105, as requested there: get the docs off the unmaintained
sphinx-pyproject and configure Sphinx directly.

sphinx-pyproject hasn't been released in ~3 years and does not support Python
3.14/3.15. It transitively pins the docs build to an old Sphinx (8.2.3), which
is what makes sphinx / build_docs fail on the 3.15 release candidate.

What changed:

  • docs/conf.py — moved every option that used to live under
    [tool.sphinx-pyproject] into a plain conf.py. Project name/version/author
    are still single-sourced from pyproject.toml (read once via the stdlib
    tomllib), so nothing about the rendered docs changes.
  • pyproject.toml — dropped the sphinx-pyproject dependency; added
    sphinx>=8.2 to the docs dependency group so Sphinx is depended on
    directly instead of pulled in transitively.
  • uv.lock — relocked. The resolver now also adds qiskit, which was in
    pyproject.toml but missing from the committed lock.

Verified locally under CPython 3.14 with the new lock:

uv sync --group=docs --frozen
uv run sphinx-build -c docs . docs/_build/html   # exit 0, Sphinx 9.1.0

The build now resolves to Sphinx 9.1.0 and completes successfully (only the
pre-existing autoapi cross-reference warnings remain).

  • Add an algorithm?
  • Fix a bug or typo in an existing algorithm?
  • Add or change doctests?
  • Documentation change?

Checklist:

  • I have read CONTRIBUTING.md.
  • This pull request is all my own work -- I have not plagiarized.
  • I know that pull requests will not be merged if they fail the automated tests.
  • All new Python files are placed inside an existing directory.
  • All filenames are in all lowercase characters with no spaces or dashes.
  • All functions and variable names follow Python naming conventions.

sphinx-pyproject has not been released in 3 years and does not support
Python 3.14/3.15, which pins the docs build to an old Sphinx (8.2.3) and
blocks the 3.15 CI work. Move its [tool.sphinx-pyproject] settings into a
plain docs/conf.py and depend on Sphinx directly.

- docs/conf.py: inline the former [tool.sphinx-pyproject] options; keep
  name/version/author single-sourced from pyproject.toml via stdlib tomllib.
- pyproject.toml: remove the sphinx-pyproject dependency; add sphinx>=8.2 to
  the docs group.
- uv.lock: relock (also picks up qiskit, which was missing from the lock).

Verified locally: uv run sphinx-build -c docs . docs/_build/html succeeds on
Sphinx 9.1.0 under CPython 3.14.
@algorithms-keeper

Copy link
Copy Markdown

Closing this pull request as invalid

@priya-sundaram-dev, this pull request is being closed as the files submitted contains an invalid extension. This repository only accepts Python algorithms. Please read the Contributing guidelines first.

Invalid files in this pull request: uv.lock

@priya-sundaram-dev

Copy link
Copy Markdown
Contributor Author

The algorithms-keeper auto-closed this because it flags any uv.lock as an invalid file extension — a false positive. The lock change here is required: this PR alters the docs dependency group (drops sphinx-pyproject, adds sphinx>=8.2), so uv.lock must be regenerated to stay consistent and pass the uv-lock pre-commit hook.

I've opened TheAlgorithms/algorithms-keeper#228 to teach the validator to accept .lock files. Once that merges I'll re-submit this cleanly. In the meantime a maintainer can merge past the keeper if desired — CI here was all green (build, build_docs, ruff, pre-commit.ci) and docs built on Sphinx 9.1 / CPython 3.14 locally.

@cclauss cclauss reopened this Aug 30, 2026
@algorithms-keeper

Copy link
Copy Markdown

Closing this pull request as invalid

@priya-sundaram-dev, this pull request is being closed as the files submitted contains an invalid extension. This repository only accepts Python algorithms. Please read the Contributing guidelines first.

Invalid files in this pull request: uv.lock

@algorithms-keeper algorithms-keeper Bot removed the awaiting reviews This PR is ready to be reviewed label Aug 30, 2026
@cclauss

cclauss commented Aug 30, 2026

Copy link
Copy Markdown
Member

Can you please revert the change to uv.lock and then ping me to reopen the PR?

@cclauss cclauss reopened this Aug 30, 2026
@algorithms-keeper

Copy link
Copy Markdown

Closing this pull request as invalid

@priya-sundaram-dev, this pull request is being closed as the files submitted contains an invalid extension. This repository only accepts Python algorithms. Please read the Contributing guidelines first.

Invalid files in this pull request: uv.lock

@priya-sundaram-dev

Copy link
Copy Markdown
Contributor Author

@cclauss Done — I've reverted the uv.lock change and force-pushed. The branch now touches only docs/conf.py and pyproject.toml (dropped the [tool.sphinx-pyproject] table, moved that config into docs/conf.py single-sourced from pyproject.toml via stdlib tomllib, and added sphinx>=8.2 to the docs dependency group). Rebased onto current master too. Ready for you to reopen — a follow-up uv lock can regenerate the lockfile for the docs-group change whenever suits you. Thanks!

@cclauss

cclauss commented Aug 30, 2026

Copy link
Copy Markdown
Member

Please make a new PR with only the docs/conf.py and pyproject.toml, and no changes to uv.lock.

In pyproject.toml, please upgrade:
beautifulsoup4>=4.15
pandas>=2.3.3

@priya-sundaram-dev

Copy link
Copy Markdown
Contributor Author

Done — opened a fresh PR #15129 with only docs/conf.py and pyproject.toml (no uv.lock changes), including the beautifulsoup4>=4.15 and pandas>=2.3.3 bumps you asked for. @cclauss

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

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants