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

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

Posted by Daniel P. Berrangé 2 years, 9 months ago

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

In v2:

 - This time with the extra trailing ',' actually committed

 docs/meson.build | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/meson.build b/docs/meson.build
index 300b134329..42d7555bc4 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 v2] docs: make sphinx-build be quiet by default

Posted by Marc-André Lureau 2 years, 8 months ago

Hi

On Tue, Aug 10, 2021 at 3:32 PM 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>
>

Without this patch, I miss the warnings 99% of the time!!

You are missing one -q though:

diff --git a/docs/meson.build b/docs/meson.build
index 42d7555bc4..51fa902cd9 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -78,7 +78,7 @@ if build_docs
                 input: files('conf.py'),
                 depfile: 'docs.d',
                 depend_files: [ sphinx_extn_depends, sphinx_template_files
],
-                command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
+                command: [SPHINX_ARGS, '-q', '-Ddepfile=@DEPFILE@',
                           '-Ddepfile_stamp=@OUTPUT0@',
                           '-b', 'html', '-d', private_dir,
                           input_dir, output_dir])

Why not update SPHINX_ARGS instead?

---

>
> In v2:
>
>  - This time with the extra trailing ',' actually committed
>
>  docs/meson.build | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/docs/meson.build b/docs/meson.build
> index 300b134329..42d7555bc4 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
>
>
>

-- 
Marc-André Lureau

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

Posted by Daniel P. Berrangé 2 years, 8 months ago

On Wed, Aug 11, 2021 at 03:22:43PM +0400, Marc-André Lureau wrote:
> Hi
> 
> On Tue, Aug 10, 2021 at 3:32 PM 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>
> >
> 
> Without this patch, I miss the warnings 99% of the time!!
> 
> You are missing one -q though:
> 
> diff --git a/docs/meson.build b/docs/meson.build
> index 42d7555bc4..51fa902cd9 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -78,7 +78,7 @@ if build_docs
>                  input: files('conf.py'),
>                  depfile: 'docs.d',
>                  depend_files: [ sphinx_extn_depends, sphinx_template_files
> ],
> -                command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
> +                command: [SPHINX_ARGS, '-q', '-Ddepfile=@DEPFILE@',
>                            '-Ddepfile_stamp=@OUTPUT0@',
>                            '-b', 'html', '-d', private_dir,
>                            input_dir, output_dir])
> 
> Why not update SPHINX_ARGS instead?

🤦 that would be a better idea.


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