Toctree error

[EDI-N]

Details

• Read the Docs project URL: https://readthedocs.org/projects/docs-ua/builds/
• Build URL (if applicable): https://readthedocs.org/projects/docs-ua/builds/13426428/
• Read the Docs username (if applicable): EDI-N

Expected Result

Read the Docs builds toctree (contents) in previous style (according to config).

Actual Result

Crashed toctree level structure at all pages and menu

[erikmannerfelt]

I think I have a related issue, which only started occurring recently.
For me, the list markers are gone, and the "Contents" title is off, just like you point toward.

I don't know if it's my code or if it was readthedocs that changed!

[Blendify]

This is caused by an unpinned dependency being automatically updated.

The bug has been fixed and the issue should be fixed by rebuilding your docs.

For the fix see readthedocs/sphinx_rtd_theme#1114

[erikmannerfelt]

Looks great now, thanks for the quick response, @Blendify!

[EDI-N]

Hello, I want to say "everything is fine", but in my case nothing change (there is same bug like it was from the beginning of this issue)... Maybe my issue isn't connected with those fix task?
For example: https://wiki.edin.ua/uk/latest/ETTN_2_0/Creation_signing_ending_rejection_ETTN_shipper.html
tocstree looks like

and same page at github: https://github.com/EDI-N/Docs_ua/blob/master/docs/ETTN_2_0/Creation_signing_ending_rejection_ETTN_shipper.rst
tocstree looks nice:

Same problem with color and style main menu caption:

   .wy-menu-vertical header,
   .wy-menu-vertical p.caption {color: #32a55c}

Can anybody help with that?

[Blendify]

It seems like older docs that are being built with and old sphinx version (1.8.5) and the theme version 0.4.3 are also affected by this bug but can't be easily patched. As a solution you can pin the latest sphinx/theme version yourself.

Poke @ericholscher I am not sure what to do here.

One possible solution would be to use the new sphinx version with sphinx 1.8.5 which should be fine. I am not sure why we pin a old sphinx version when the old sphinx version is also used. 0.5.2 is compatible with sphinx 1.8.5

[stsewd]

Mainly for backwards compatibility, you should put the specific version of the theme and sphinx in your requirements file https://github.com/EDI-N/Docs_ua/blob/master/docs/requirements.txt

[EDI-N]

I have conflict is caused by:
The user requested Sphinx==1.8.5
sphinxcontrib-contentui 0.2.5 depends on Sphinx>=2.0
What version is recommended to use?
I need to add it like this?:

Sphinx==3.0
sphinx_rtd_theme==2.0

P.S.
Seems that page also have same problem:

[stsewd]

@EDI-N the version of the theme you need is 0.5.2, the latest version of sphinx should work as well.

[EDI-N]

@stsewd thanks for fast response. Now everything works nice. Need to add to requirements.txt latest versions sphinx & sphinx_rtd_theme:

sphinx_rtd_theme==0.5.2
sphinx==3.5.3

[Blendify]

This still needs to be fixed for projects that don't specify new sphinx versions manually.

[Gallaecio]

Shouldn’t this already get the latest versions of everything by not hardcoding a specific version?

Sphinx>=3.0
sphinx_rtd_theme>=0.4

Because that’s (part of) the requirements.txt file in Scrapy, and we are seeing the same issue. An old build looks fine, but the same code built now looks bad.

[Gallaecio]

Answering myself: no.

Read The Docs installs some base dependencies, such as sphinx-rtd-theme<0.5, and any requirement that does not impose a newer version than the one Read The Docs already installs will simply reuse the installed dependency.

Since the issue here is that docutils 0.17 breaks all versions of sphinx_rtd_theme currently released, we need to either add a requirement for sphinx_rtd_theme>=0.5.2 (sphinx_rtd_theme>0.5 would work as well) or for docutils<0.17 (which is what sphinx_rtd_theme 0.5.2 does).

In Scrapy we had the added issue that we were forcing the installation of an older pip, before the dependency resolution changes, and sphinx_rtd_theme>=0.5.2 did not cause docutils<0.17 to be installed, it just caused a warning about the conflict. The issues preventing us from using the latest pip no longer seem to affect us, though, so we just went back to using the latest pip.

[Gallaecio]

I wonder if Read The Docs should use --upgrade-strategy earger when installing user requirements, to avoid preinstalled versions from capping user requirements that allow for newer dependency versions.

[stsewd]

I wonder if Read The Docs should use --upgrade-strategy earger when installing user requirements, to avoid preinstalled versions from capping user requirements that allow for newer dependency versions.

New projects (projects created after Oct 20, 2020) use the latest version of sphinx and the rtd theme by default. In the future we may stop installing the theme by default, so users would need to provide their requirements explicitly (#7859).

[stsewd]

There isn't much we can do here, we already recommend users to pin their dependencies. Sphinx already released a new version that pins docutils. We may stop installing some packages by default as discussed in #8103