1

I used to keep a project docs on readthedocs.io server. Here is the link CoFEA Initiative

Since the 3rd of April, it looks a bit broken (e.g. the main logo is aligned to the left while it should be centered) because a new version of docutils library was released. The latest version of docutils is 0.17, and this particular Sphinx theme works fine with version up to 0.16.

The log file shows why it is not working. First, the readthedocs server installs latest version of docutils

Collecting docutils>=0.11
  Downloading docutils-0.17-py2.py3-none-any.whl (575 kB)

Then the Sphinx theme tries to download and install a specific version of docutils based on what is defined in the setup.py

Installed /home/docs/checkouts/readthedocs.org/user_builds/cofea/envs/latest/lib/python3.7/site-packages/ipygany-0.5.0-py3.7.egg
Searching for docutils==0.16
Reading https://pypi.org/simple/docutils/
Downloading https://files.pythonhosted.org/packages/81/44/8a15e45ffa96e6cf82956dd8d7af9e666357e16b0d93b253903475ee947f/docutils-0.16-py2.py3-none-any.whl#sha256=0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af
Best match: docutils 0.16
Processing docutils-0.16-py2.py3-none-any.whl
Installing docutils-0.16-py2.py3-none-any.whl to /home/docs/checkouts/readthedocs.org/user_builds/cofea/envs/latest/lib/python3.7/site-packages

I think what is happening is that when the Sphinx command is invoked, it is using the version 0.17 instead of 0.16.

Is there any way to enforce usage of docutils 0.16 versions for Sphinx?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Spike1991
  • 31
  • 6
  • You need to show your `setup.py`, your `pyproject.toml`, your `readthedocs.yaml`, etc. – sinoroc Apr 05 '21 at 07:48
  • @sinoroc thank you for coming back to me. The setup.py and the readthedocs.yaml can be found on https://github.com/spolanski/CoFEA I haven't seen the project.toml file before so I need to check it – Spike1991 Apr 05 '21 at 08:06
  • OK, no need for a `pyproject.toml`. But you should edit your question to add the content of `setup.py` and `.readthedocs.yml`, so that you have a self-contained question. – sinoroc Apr 05 '21 at 08:31
  • I guess I am not understanding the issue. From what you are saying (via the linked logfile), docutils 0.16 is installed last so I guess this is also this version that is being used. No? Are you sure it is the 0.17 version that is being imported in the end? Have you tried this locally for comparison? – sinoroc Apr 05 '21 at 08:49
  • It looks like the docutils 0.16 are installed last but sphinx seems to use the 0.17 version which is installed at the top. I recreated locally the wrong behaviour using virtualenv module. I just clone the repo and do python setup.py install in venv. When version 0.16 is defined in setup.py then it works just fine. When 0.17 is defined then it is showing exactly the same issue as the online version. To fix the issue I would need to point readthedocs to use docutils 0.16 when sphinx is invoked, but I don't know how to do it – Spike1991 Apr 05 '21 at 09:11
  • 1
    Surprising behavior to me. I do not understand how it could happen that 0.16 is installed last but 0.17 is imported. -- Maybe try setting the `pip` install method in `.readthedocs.yml` instead of `setuptools`. – sinoroc Apr 05 '21 at 09:22
  • Thanks a lot! Changing setuptools to pip solved the issue! – Spike1991 Apr 05 '21 at 10:27
  • Good. Generally setuptools should not be used to install things anymore. Whenever possible reach out to an actual installer (like pip) instead. setuptools is not trying to be an actual installer anymore, these functionalities are outdated/deprecated in setuptools. Setuptools is basically just a "build back-end" now. – sinoroc Apr 05 '21 at 10:33

1 Answers1

3

I had a similar issue:

ERROR: sphinx-rtd-theme 0.5.2 has requirement docutils<0.17, but you'll have docutils 0.17.1 which is incompatible.

The order in the install command fixed the issue for me. This command failed with installing docutils 0.17:

pip3 install sphinx sphinx-rtd-theme

This one was successful with installing docutils 0.16:

pip3 install sphinx-rtd-theme sphinx
bad_coder
  • 11,289
  • 20
  • 44
  • 72
krutz
  • 31
  • 2