Merge pull request #298 from samdoran/docs/pin-requirements

Add configuration for Read the Docs build and pin docs requirements

Due to a recent release of docutils 0.18, our doc build is broken.
Add configuration for Read the Docs and pip docs requirements to ensure builds will not spontaneously break in the future.
Update tox configuration to match the build done by Read the Docs.

Reviewed-by: David Shrewsbury <None>
Reviewed-by: None <None>

.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: 2
+
+formats:
+  - epub
+  - pdf
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: '3.10'
+
+sphinx:
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/requirements.in

@@ -0,0 +1,3 @@
+pbr
+sphinx
+six

docs/requirements.txt

@@ -1,3 +1,25 @@
-pbr
-sphinx
-six
+alabaster==0.7.12
+Babel==2.9.1
+certifi==2021.10.8
+charset-normalizer==2.0.7
+docutils==0.17.1
+idna==3.3
+imagesize==1.2.0
+Jinja2==3.0.2
+MarkupSafe==2.0.1
+packaging==21.0
+pbr==5.6.0
+Pygments==2.10.0
+pyparsing==3.0.3
+pytz==2021.3
+requests==2.26.0
+six==1.16.0
+snowballstemmer==2.1.0
+Sphinx==4.2.0
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+urllib3==1.26.7

tox.ini

@@ -42,6 +42,8 @@ commands =
     bash -c 'pytest test/integration -v -n `python -c "import multiprocessing; print(int(multiprocessing.cpu_count()/2))"` --junitxml=artifacts/results.xml {posargs}'
 
 [testenv:docs]
+description = Build documentation
 deps = -r{toxinidir}/docs/requirements.txt
+skip_install = True
 commands =
-    sphinx-build -E -W -d docs/build/doctrees -b html docs docs/build/html
+    sphinx-build -T -E -W -n --keep-going {tty:--color} -j auto -d docs/build/doctrees -b html docs docs/build/html