Run Sphinx on CI to catch errors/warnings

[huonw]

This adds a CI step that runs Sphinx, and catches errors and warnings. This will help us keep our documentation rendering as good as possible.

It takes this approach rather than just setting fail_on_warning: true in the .readthedocs.yaml configuration file because we can get clearer and better error messages and description.

Example output, with the problems from before #1360 was fixed: https://buildkite.com/stellar/stellargraph-public/builds/3994#annotation-sphinx-doc-build

See: #1432

[codeclimate]

Code Climate has analyzed commit a9ac99c and detected 0 issues on this pull request.

View more on Code Climate.

[timpitman]

just a small question about requirements, but this looks excellent - much easier to see than digging in readthedocs 👍 📖

[timpitman]

I'm not entirely sue why our existing doc requirements were pinned? rtd itself appears to install sphinx-rtd-theme<0.5

[huonw]

Yeah, I don't quite know why either. I guess it ensures our docs don't break accidentally, but maybe it's suboptimal for this, because we won't automatically pick up improvements to the theme. However, I think these will overrule the RtDs defaults (that is, our requirements here will be the ones that are used for rendering the docs online).

For reference, it seems like RtD uses:

Pygments==2.3.1
setuptools==41.0.1
docutils==0.14
mock==1.0.1
pillow==5.4.1
alabaster>=0.7,<0.8,!=0.7.5
commonmark==0.8.1
recommonmark==0.5.0
sphinx<2
sphinx-rtd-theme<0.5
readthedocs-sphinx-ext<1.1

Notably, they're using a very old Sphinx version there. Our CI is now installing Sphinx==3.0.3. Maybe we should add more things to our requirements to ensure CI and RtDs are more similar?

[timpitman]

I couldn't find any documentation on why rtd pre-installs specific old versions of packages, not sure that we want to add what they've already go in requirements.txt, as it may change?

[huonw]

I've added the exact requirements specified by RtD into this PR, and opened #1537 to upgrade the versions to the current latest ones. I've done it this way so that this PR (theoretically) doesn't change anything at all about how our docs are rendered, and is just focused on getting accurate CI, and then #1537 can be independently tested and the rendering verified.

[TheDen]

LGTM 👍

Just one thing on the agent EC2 type, since I'm not familiar with Sphinx's resource requirements

[TheDen]

Could this run potentially run successfully on the default queue (t2micro)?

[huonw]

I suspect it might be able to, but it would likely require pulling the runner-3_6 image. I've been trying to keep steps using those images on t2medium and t2large instances, to have more cache hits.

[TheDen]

Fair enough 👍