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

["Daniel P. Berrangé" <berrange@redhat.com>]

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