search

dask / dask-sphinx-theme

Sphinx theme for Dask documentation
BSD 3-Clause "New" or "Revised" License
6 stars 15 forks source link

Updating `sphinx-book-theme` version pinning #68

Open kloczek opened 2 years ago

kloczek commented 2 years ago

https://github.com/dask/dask-sphinx-theme/blob/cc0262ee6fa5f52cd1064aae17b1d317443d6f68/requirements.txt#L1

jrbourbeau commented 2 years ago

It looks like we pinned to that specific version of sphinx-book-theme to avoid breaking due to upstream changes in the theme. See https://github.com/dask/dask-sphinx-theme/pull/62 for more context. Updating to a more recent sphinx-theme-version seems like a nice thing to do, I just don't think anyone had gotten around to it yet? Is this something you're interested in working on (no obligation though)

Also, just wanted to note that there has been some thought to moving to a different theme at some point https://github.com/dask/dask-sphinx-theme/pull/67

scharlottej13 commented 2 years ago

@jrbourbeau I'm happy to update the version alongside my work in #67, I think with all the css customizations there may not be a lot of reason to change from sphinx-book-theme.

scharlottej13 commented 2 years ago

@kloczek my apologies! I did not get a chance to do this. Feel free to work on these updates if you are interested.

kloczek commented 2 years ago

Really sorry but I have really long list of other modules to package 😢 I've trimmed current dependencies a bit in my build procedure using below patch

--- a/requirements.txt~ 2022-02-24 10:33:16.000000000 +0000
+++ b/requirements.txt  2022-05-13 09:48:13.040022114 +0000
@@ -1,2 +1,2 @@
-sphinx-book-theme==0.2.0
+sphinx-book-theme>=0.2.0
 jsonschema

And looks like (so far) no visible side effects. With that I can wait .. don't worry. Take your time 👍

consideRatio commented 6 months ago

I've observed this to be leading to errors in building docs.

dask-sphinx-theme pins sphinx-book-theme==0.2.0 still, and that makes us stuck at sphinx>=3,<5, and that now has observed to lead to the error below in dask/dask-gateway:

Sphinx version error:
The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.
make: *** [Makefile:20: html] Error 2

Note that dask/dask-gateway doesn't itself enable sphinxcontrib.applehelp, and I've not seen it mentioned by either dask-sphinx-theme or its dependent sphinx-book-theme.

Okay it seems to stem from sphinx itself, and sphinxcontrib-applehelp 1.0.5 introduced the breaking change as seen here.

Requirement already satisfied: sphinxcontrib-applehelp in /home/erik/miniforge3/lib/python3.10/site-packages (from sphinx<5,>=3->sphinx-book-theme==0.2.0->dask-sphinx-theme) (1.0.8)

It appears that multiple dependencies installed by sphinx require sphinx>=5, so a simpler workaround like pinning sphinxcontrib-applehelp<1.0.5 doesn't work.

Workaround

This docs requirements.txt addition to dask/dask-gateway's docs dependencies made its CI build succeed again:

# FIXME: This workaround is required until we have sphinx>=5, as enabled by
#        dask-sphinx-theme no longer pinning sphinx-book-theme==0.2.0. This is
#        tracked in https://github.com/dask/dask-sphinx-theme/issues/68.
#
sphinxcontrib-applehelp<1.0.5
sphinxcontrib-devhelp<1.0.6
sphinxcontrib-htmlhelp<2.0.5
sphinxcontrib-serializinghtml<1.1.10
sphinxcontrib-qthelp<1.0.7