Pin Sphinx version exactly for build depending on Python version
purva-thakre opened this issue · 4 comments
At this link, a line is given to install doc build dependencies. The problem is that it installs the latest version of Sphinx which has an issue with missing colon when documentation is built.
When I build documentation locally, the colon in the screenshot after inpt below does not appear.
I use Python 3.8 in my virtual environment which is incompatible with the Sphinx version specified in this configuration file. So, to install this older version of Sphinx, a user will also have to make sure they switch to Python 3.6. This will also end up installing older versions of many dependencies.
For more information, see the fix applied by RTD and the issues references within for an earlier version of Sphinx . One of the issues in the RTD link discusses enforcing the build in html4 or making changes in CSS to avoid this error (don't know if any of these would fix it or not).
needs_sphinx is a minimal version, it's fine to use higher versions. I used Sphinx 3.5.3 on Python 3.8 to build the 4.6 documentation that's live on the website right now. That has the colon you're talking about. As I understand it, it's not a Sphinx issue, it's a sphinx-rtd-theme issue, which also seems backed up by your links.
I used sphinx-rtd-theme=0.5.2, which notes that there's a temporary incompatibility with docutils=0.17 and so it forcefully installs docutils=0.16 instead.
That said, of course you're right that the documentation build guide is very out-of-date. I'll just test a basic config and then dump a requirements.txt file and updated instructions into the readme to make it a bit more reproducible.
I think my issue could also have been caused by installing an older version of sphinx-rtd-theme. Compared to your version, mine is an older version. I installed it using conda and it appears to not have been updated for a while.
@jakelishman Closing this because it was indeed an issue of older version of sphinx-rtd-theme due to conda install sphinx-rtd-theme. The recommended way to install it is via pip and not conda. The build guide will need to be updated accordingly.