Dependencies: add minimum docutils version #281
Conversation
|
the preview doesn't show this as fixed - but looking at the html from the preview, it's still using so the workflow must be caching the dependencies somehow. |
|
The requirements are installed from |
|
oops! Thanks for explaining, I'll run the pip-compile command and update the PR |
|
Updated, and now the preview is fixed as expected 😄 Thanks for the help on the CI side, sorry for not noticing that requirements.txt file myself! |
|
Thanks for the PR. No need to sorry 😉 Tests are broken because |
pyproject.toml
Outdated
| # not needed directly, but ends up | ||
| # in dependency graph and lower | ||
| # versions cause issues | ||
| "docutils>=0.20.0", |
There was a problem hiding this comment.
Do you know what's the extension that doesn't support docutils>0.18?
There was a problem hiding this comment.
It looks like it's sphinxcontrib-bibtex:
mcmtroffaes/sphinxcontrib-bibtex@ba61382 (with follow up commit to fix error: mcmtroffaes/sphinxcontrib-bibtex@f60c7ce )
Although I must confess I haven't looked fully into what exactly causes the weird html output as I was sufficiently satisfied this was the problem.
Shall I edit the comment to something more specific, like:
| # not needed directly, but ends up | |
| # in dependency graph and lower | |
| # versions cause issues | |
| "docutils>=0.20.0", | |
| # not needed directly, but | |
| # lower versions cause issues with | |
| # sphinxcontrib-bibtex, see | |
| # https://github.com/mcmtroffaes/sphinxcontrib-bibtex/commit/ba613822a65cd685e02cc2692afc1dd0efa8b90f | |
| "docutils>=0.20.0", |
of course, an alternative is to just add a minimum version of sphinxcontrib-bibtex of 2.6.0 for the docs, where they have the relevant version pin for docutils themselves. However, that does exclude versions of sphinxcontrib-bibtex that work correctly (as long as they get the right version of docutils). What do you think?
There was a problem hiding this comment.
Pinning to 2.6.0 looks like a clearer approach to me 👍🏼 . You can explain this in a comment next to this pin.
There was a problem hiding this comment.
Done! sorry for the delay, I'm on holiday this week, but should be able to keep on top of this now.
There was a problem hiding this comment.
Enjoy your holidays! This can definitely wait. There is no rush 😉
Happy to add the pins for the relevant dependency - I just saw #279 though and your comment about doing a new release for Sphinx>=5.0 - I think maybe that's the better solution? Most end users will be using sphinx >5 anyway, so it would save force users for whom everything is working fine from using an older version of sphinx's dependencies than necessary for them. what would you think of merging this pr 'as-is', or potentially modifying the tox setup to not test Sphinx versions below 5.0, and then following up with a release requirement Sphinx 5.0 or newer? |
I think we should do all of that, yes 😄
Would you like to work on these? I'm happy to continue reviewing and helping you here. |
Sure - I'll start work on a PR to update tox and update the pyproject.toml and changelog etc. for the new release. For the actual release, shall I leave the running of the final For this PR, are you happy to merge now, or do you want to wait for the tox test update? |
Yes.
Let's wait for the tox updates so we are sure everything is on it's place 👍🏼 |
|
@humitos I've updated this now, and all looks ok to me (assuming the tests pass), let me know if there's anything else you want me to do on it! |
Otherwise the lack of a pin on docutils causes bad html rendering. Docutils versions lower than 0.20 cause rendering problems in the usage page with the bibliography, see #280. upgrade docs/requirements.txt with pip-compile after the pyproject.toml change.
Closes #280
Versions lower than 0.20 cause rendering problems in the usage page with the bibliography, see #280.
📚 Documentation preview 📚: https://sphinx-hoverxref--281.org.readthedocs.build/en/281/