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

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

[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.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 .travis.yml | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index 1054ec5d29..f5208301d6 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -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:
-- 
2.28.0

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

[Eduardo Habkost]

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

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 .travis.yml | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index f5208301d6..626b61b077 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -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
 
 
-- 
2.28.0

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

[Daniel P. Berrangé]

On Mon, Oct 19, 2020 at 10:31:08AM -0400, Eduardo Habkost wrote:
> 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.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  .travis.yml | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/.travis.yml b/.travis.yml
> index 1054ec5d29..f5208301d6 100644
> --- a/.travis.yml
> +++ b/.travis.yml
> @@ -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

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
-- 
|: 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 :|