Unclear sphinx pin in pyproject.toml

[rossbar]

Describe the bug

The pyproject.toml contains the following pin:

sphinx-book-theme/pyproject.toml

Line 61 in 9ed62f5

"sphinx~=4.0", # Force Sphinx to be the latest version

From the comment, it is unclear whether this pin to the sphinx 4.X series is intentional or not, since "latest" == 5.X.

If the pin to sphinx 4.X is intentional, an update to the comment would be sufficient. FWIW the pin does seem to be important in that we have projects that build with sphinx 4.X but not 5.X, though I suspect the real problem is transitive dependencies (e.g. docutils). See numpy/numpy-tutorials#136.

Reproduce the bug

N/A

List your environment

N/A

[DominiqueMakowski]

Currently, installing sphinx-book-theme indeed downgrades the version of sphinx to 4.5 if the latest is installed (5.0.2), causing some downstream issues...

[pradyunsg]

See executablebooks/meta#750.

[rossbar]

@pradyunsg maybe I'm misunderstanding the checkmarks in the linked issue, but it looks like there's a discrepancy between the issue listing and the pin in sphinx-book-theme. sphinx-book-theme is pinned to ~= 4.0 on both master and the latest tagged release v0.3.2. Does this mean the checks in the linked meta-issue indicate that the checked libraries are not pinned to sphinx < 5? If so, the wording in the issue could probably use some clarification.

Note also that my original comment was about the comment in the pyproject.toml - sphinx 4 is no longer the "latest" sphinx, so if the intention is to pin sphinx-book-theme to the sphinx 4 series for now (this seems to be the case) then the comment wording should be updated. It's a very straightforward change but I just want to make sure that I'm understanding everything correctly.

[pradyunsg]

Indeed, that checklist is for which repositories need to be migrated still. Those that are ticked are migrated and Sphinx-5 ready. The rest are not. I've updated the issuue title and text to more clearly reflect that. :)

IIUC, the blocker for this theme is indeed docutils -- since Sphinx 5 allows using docutils 18 (and 19?) which has backwards incompatible changes.