[PATCH] docs: make sphinx-build be quiet by default

[PATCH] docs: make sphinx-build be quiet by default

[Daniel P. Berrangé]

The sphinx-build is fairly verbose spitting out pages of output to the
console, which causes errors from other build commands to be scrolled
off the top of the terminal. This can leave the mistaken impression that
the build passed, when in fact there was a failure.

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 300b134329..29e119a3cc 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -21,7 +21,7 @@ if sphinx_build.found()
   run_command('mkdir', ['-p', tmpdir / 'sphinx'])
   run_command('touch', [tmpdir / 'sphinx/index.rst'])
   sphinx_build_test_out = run_command(SPHINX_ARGS + [
-    '-c', meson.current_source_dir(),
+    '-q', '-c', meson.current_source_dir(),
     '-b', 'html', tmpdir / 'sphinx',
     tmpdir / 'sphinx/out'])
   build_docs = (sphinx_build_test_out.returncode() == 0)
@@ -98,8 +98,9 @@ if build_docs
                               input: this_manual,
                               install: build_docs,
                               install_dir: install_dirs,
-                              command: [SPHINX_ARGS, '-b', 'man', '-d', private_dir,
-                                        input_dir, meson.current_build_dir()])
+                              command: [SPHINX_ARGS, '-q', '-b', 'man',
+                                        '-d', private_dir, input_dir
+                                        meson.current_build_dir()])
 
   alias_target('sphinxdocs', sphinxdocs)
   alias_target('html', sphinxdocs)
-- 
2.31.1

Re: [PATCH] docs: make sphinx-build be quiet by default

[Peter Maydell]

On Tue, 10 Aug 2021 at 12:01, Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> The sphinx-build is fairly verbose spitting out pages of output to the
> console, which causes errors from other build commands to be scrolled
> off the top of the terminal. This can leave the mistaken impression that
> the build passed, when in fact there was a failure.
>
> 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 300b134329..29e119a3cc 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -21,7 +21,7 @@ if sphinx_build.found()
>    run_command('mkdir', ['-p', tmpdir / 'sphinx'])
>    run_command('touch', [tmpdir / 'sphinx/index.rst'])
>    sphinx_build_test_out = run_command(SPHINX_ARGS + [
> -    '-c', meson.current_source_dir(),
> +    '-q', '-c', meson.current_source_dir(),
>      '-b', 'html', tmpdir / 'sphinx',
>      tmpdir / 'sphinx/out'])
>    build_docs = (sphinx_build_test_out.returncode() == 0)
> @@ -98,8 +98,9 @@ if build_docs
>                                input: this_manual,
>                                install: build_docs,
>                                install_dir: install_dirs,
> -                              command: [SPHINX_ARGS, '-b', 'man', '-d', private_dir,
> -                                        input_dir, meson.current_build_dir()])
> +                              command: [SPHINX_ARGS, '-q', '-b', 'man',
> +                                        '-d', private_dir, input_dir
> +                                        meson.current_build_dir()])
>
>    alias_target('sphinxdocs', sphinxdocs)
>    alias_target('html', sphinxdocs)

Can we make meson pass '-q' only for non-verbose builds, so that
if you pass make 'V=1' you still get the verbose sphinx output ?

thanks
-- PMM

Re: [PATCH] docs: make sphinx-build be quiet by default

[Daniel P. Berrangé]

On Tue, Aug 10, 2021 at 12:06:47PM +0100, Peter Maydell wrote:
> On Tue, 10 Aug 2021 at 12:01, Daniel P. Berrangé <berrange@redhat.com> wrote:
> >
> > The sphinx-build is fairly verbose spitting out pages of output to the
> > console, which causes errors from other build commands to be scrolled
> > off the top of the terminal. This can leave the mistaken impression that
> > the build passed, when in fact there was a failure.
> >
> > 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 300b134329..29e119a3cc 100644
> > --- a/docs/meson.build
> > +++ b/docs/meson.build
> > @@ -21,7 +21,7 @@ if sphinx_build.found()
> >    run_command('mkdir', ['-p', tmpdir / 'sphinx'])
> >    run_command('touch', [tmpdir / 'sphinx/index.rst'])
> >    sphinx_build_test_out = run_command(SPHINX_ARGS + [
> > -    '-c', meson.current_source_dir(),
> > +    '-q', '-c', meson.current_source_dir(),
> >      '-b', 'html', tmpdir / 'sphinx',
> >      tmpdir / 'sphinx/out'])
> >    build_docs = (sphinx_build_test_out.returncode() == 0)
> > @@ -98,8 +98,9 @@ if build_docs
> >                                input: this_manual,
> >                                install: build_docs,
> >                                install_dir: install_dirs,
> > -                              command: [SPHINX_ARGS, '-b', 'man', '-d', private_dir,
> > -                                        input_dir, meson.current_build_dir()])
> > +                              command: [SPHINX_ARGS, '-q', '-b', 'man',
> > +                                        '-d', private_dir, input_dir
> > +                                        meson.current_build_dir()])
> >
> >    alias_target('sphinxdocs', sphinxdocs)
> >    alias_target('html', sphinxdocs)
> 
> Can we make meson pass '-q' only for non-verbose builds, so that
> if you pass make 'V=1' you still get the verbose sphinx output ?

The meson.build rules are turned into a ninja.build file at configure time.
IOW, at the time that conversion happens the V=1 arg isn't present, so we
can't conditionally pass '-q'. 

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

Re: [PATCH] docs: make sphinx-build be quiet by default

[Peter Maydell]

On Tue, 10 Aug 2021 at 12:13, Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Tue, Aug 10, 2021 at 12:06:47PM +0100, Peter Maydell wrote:
> > Can we make meson pass '-q' only for non-verbose builds, so that
> > if you pass make 'V=1' you still get the verbose sphinx output ?
>
> The meson.build rules are turned into a ninja.build file at configure time.
> IOW, at the time that conversion happens the V=1 arg isn't present, so we
> can't conditionally pass '-q'.

I'd rather have "always verbose" than "never verbose" then, I think.

Also, this seems like a meson/ninja misfeature if we can't do
a perfectly sensible thing. We can do it for cc, why not sphinx?

thanks
-- PMM

Re: [PATCH] docs: make sphinx-build be quiet by default

[Daniel P. Berrangé]

On Tue, Aug 10, 2021 at 01:48:51PM +0100, Peter Maydell wrote:
> On Tue, 10 Aug 2021 at 12:13, Daniel P. Berrangé <berrange@redhat.com> wrote:
> >
> > On Tue, Aug 10, 2021 at 12:06:47PM +0100, Peter Maydell wrote:
> > > Can we make meson pass '-q' only for non-verbose builds, so that
> > > if you pass make 'V=1' you still get the verbose sphinx output ?
> >
> > The meson.build rules are turned into a ninja.build file at configure time.
> > IOW, at the time that conversion happens the V=1 arg isn't present, so we
> > can't conditionally pass '-q'.
> 
> I'd rather have "always verbose" than "never verbose" then, I think.
> 
> Also, this seems like a meson/ninja misfeature if we can't do
> a perfectly sensible thing. We can do it for cc, why not sphinx?

This patch is trying to make sphinx behave the same way as CC.

With CC by default you get "Compiling C object ...." and with V=1
you get the gcc command line printed.

With sphinx you now get "Generating QEMU manual with a custom command"
and with V=1 you get the sphinx-build command line printed.

In both cases you'll get errors printed to stderr by gcc/sphinx

There is no case in which GCC would print verbose progress information
reading source/header files to stdout, which is what sphinx currently
does without '-q'

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