It is hard to diagnose why Sphinx fails in a CI environment, as we
discard the stdout/err and just print a generic error message.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/meson.build | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/meson.build b/docs/meson.build
index 8c222f96bb..278098dd4f 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -20,14 +20,15 @@ if sphinx_build.found()
   # version requirement). This will fail if sphinx-build is too old.
   run_command('mkdir', ['-p', tmpdir / 'sphinx'])
   run_command('touch', [tmpdir / 'sphinx/index.rst'])
-  sphinx_build_test_out = run_command(SPHINX_ARGS + [
+  sphinx_cmd = run_command(SPHINX_ARGS + [
     '-c', meson.current_source_dir(),
     '-b', 'html', tmpdir / 'sphinx',
     tmpdir / 'sphinx/out'])
-  build_docs = (sphinx_build_test_out.returncode() == 0)
+  build_docs = (sphinx_cmd.returncode() == 0)
 
   if not build_docs
-    warning('@0@ exists but it is either too old or uses too old a Python version'.format(get_option('sphinx_build')))
+    warning('@0@ exists but it is either too old or uses too old a Python version\nstdout:@1@\nstderr:@2@'.format(
+      get_option('sphinx_build'), sphinx_cmd.stdout().strip(), sphinx_cmd.stderr().strip()))
     if get_option('docs').enabled()
       error('Install a Python 3 version of python-sphinx')
     endif
-- 
2.28.0

On Mon, 2 Nov 2020 at 13:09, Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> It is hard to diagnose why Sphinx fails in a CI environment, as we
> discard the stdout/err and just print a generic error message.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

This kind of detailed-diagnostics should go into whatever
meson's equivalent of config.log is. There's an argument
for printing it if the user asked for --enable-docs specifically,
but if we're doing the usual "see if it works, use it if it does"
logic then we shouldn't be printing diagnostic logging from
Sphinx (which can be pretty ugly and longwinded) in the middle
of the meson output, IMHO.

thanks
-- PMM

On Mon, Nov 02, 2020 at 01:48:00PM +0000, Peter Maydell wrote:
> On Mon, 2 Nov 2020 at 13:09, Daniel P. Berrangé <berrange@redhat.com> wrote:
> >
> > It is hard to diagnose why Sphinx fails in a CI environment, as we
> > discard the stdout/err and just print a generic error message.
> >
> > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> 
> This kind of detailed-diagnostics should go into whatever
> meson's equivalent of config.log is. There's an argument
> for printing it if the user asked for --enable-docs specifically,
> but if we're doing the usual "see if it works, use it if it does"
> logic then we shouldn't be printing diagnostic logging from
> Sphinx (which can be pretty ugly and longwinded) in the middle
> of the meson output, IMHO.

Turns out this is already recorded in build/meson-logs/meson-log.txt
by default. We can probably publish the file as an artifact in
gitlab CI to aid debugging.

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