Skip to contentSkip to conversation

travis: Check if docs can be built with multiple Sphinx versions

PATCH In review Eduardo Habkost 2 participants 3 messages Oct 19, 2020

lore
Share & tools
lore
#0 lore raw

PATCH 1/2 travis: Check if docs can be built with multiple Sphinx versions

Add new jobs to .travis.yml to test if docs can be built with multiple Sphinx versions: 1.6.1, latest 1.x, 2.0.0, and latest 2.x.

---
 .travis.yml | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
.travis.yml +37 -0
index 1054ec5d29..f5208301d6 100644
@@ -181,6 +181,43 @@ jobs:
             - perl
 
 
+    # Check we can build docs with multiple Sphinx versions.
+    # We need --sphinx-build=sphinx-build to ensure we use the
+    # sphinx-build binary installed by pip.
+
+    # 1.6.1 is the oldest Sphinx version we support
+    - name: "docs (Sphinx 1.6.1)"
+      env:
+        - CONFIG="--enable-docs --sphinx-build=sphinx-build"
+      install:
+        - pip install -q sphinx==1.6.1
+      script:
+        - make -j${JOBS} sphinxdocs
+    - name: "docs (Sphinx 1.x)"
+      env:
+        - CONFIG="--enable-docs --sphinx-build=sphinx-build"
+      install:
+        # install latest 1.x version
+        - pip install -q 'sphinx>=1.0,<2.0'
+      script:
+        - make -j${JOBS} sphinxdocs
+    - name: "docs (Sphinx 2.0.0)"
+      env:
+        - CONFIG="--enable-docs --sphinx-build=sphinx-build"
+      install:
+        - pip install -q sphinx==2.0.0
+      script:
+        - make -j${JOBS} sphinxdocs
+    - name: "docs (Sphinx 2.x)"
+      env:
+        - CONFIG="--enable-docs --sphinx-build=sphinx-build"
+      install:
+        # install latest 2.x version
+        - pip install -q 'sphinx>=2.0,<3.0'
+      script:
+        - make -j${JOBS} sphinxdocs
+
+
     # Test with Clang for compile portability (Travis uses clang-5.0)
     - name: "Clang (user)"
       env:
Signature · 1 line
2.28.0
#1 lore raw

PATCH 2/2 travis: Remove docs from "tools and docs" job

We have other jobs that will test documentation builds, so we don't need to build docs in that job.

---
 .travis.yml | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
.travis.yml +3 -4
index f5208301d6..626b61b077 100644
@@ -166,18 +166,17 @@ jobs:
         - TEST_CMD="make check-unit -j${JOBS} V=1"
 
 
-    # Check we can build docs and tools (out of tree)
-    - name: "tools and docs (bionic)"
+    # Check we can build tools (out of tree)
+    - name: "tools (bionic)"
       dist: bionic
       env:
         - BUILD_DIR="out-of-tree/build/dir" SRC_DIR="../../.."
-        - BASE_CONFIG="--enable-tools --enable-docs"
+        - BASE_CONFIG="--enable-tools --disable-docs"
         - CONFIG="--target-list=x86_64-softmmu,aarch64-linux-user"
         - CACHE_NAME="${TRAVIS_BRANCH}-linux-gcc-default"
       addons:
         apt:
           packages:
-            - python3-sphinx
             - perl
 
 
Signature · 1 line
2.28.0
#2 lore raw
In reply to Eduardo Habkost
Quoted 42 lines · Eduardo Habkost

Add new jobs to .travis.yml to test if docs can be built with multiple Sphinx versions: 1.6.1, latest 1.x, 2.0.0, and latest 2.x.

---
 .travis.yml | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
.travis.yml +25 -0
index 1054ec5d29..f5208301d6 100644
@@ -181,6 +181,43 @@ jobs:
             - perl
 
 
+    # Check we can build docs with multiple Sphinx versions.
+    # We need --sphinx-build=sphinx-build to ensure we use the
+    # sphinx-build binary installed by pip.
+
+    # 1.6.1 is the oldest Sphinx version we support
+    - name: "docs (Sphinx 1.6.1)"
+      env:
+        - CONFIG="--enable-docs --sphinx-build=sphinx-build"
+      install:
+        - pip install -q sphinx==1.6.1
+      script:
+        - make -j${JOBS} sphinxdocs
+    - name: "docs (Sphinx 1.x)"
+      env:
+        - CONFIG="--enable-docs --sphinx-build=sphinx-build"
+      install:
+        # install latest 1.x version
+        - pip install -q 'sphinx>=1.0,<2.0'
+      script:
+        - make -j${JOBS} sphinxdocs
+    - name: "docs (Sphinx 2.0.0)"
+      env:
+        - CONFIG="--enable-docs --sphinx-build=sphinx-build"
+      install:
+        - pip install -q sphinx==2.0.0

.travis.yml jobs: · line 218

Quoted 10 lines
.travis.yml +10 -0
+      script:
+        - make -j${JOBS} sphinxdocs
+    - name: "docs (Sphinx 2.x)"
+      env:
+        - CONFIG="--enable-docs --sphinx-build=sphinx-build"
+      install:
+        # install latest 2.x version
+        - pip install -q 'sphinx>=2.0,<3.0'
+      script:
+        - make -j${JOBS} sphinxdocs

We shouldn't be adding new jobs to Travis CI.

In terms of sphinx versions, we only need to care about versions that correspond to our supported distro platforms. We have dockerfiles that we build in GitLab CI for all our important Linux platforms. Some, but not all, of the dockerfiles include sphinx already.

IOW, we should add the sphinx RPM to all the dockerfiles that don't already contain it - centos are the most notable ones missing it.

Then we should make sure there are GitLab CI jobs are trigger the docs build in all distros that are needed to give this level of coverage. There shouldn't be a need to install stuff from pip in this case.

Regards,
Daniel

Signature · 3 lines
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|