Skip to contentSkip to conversation

docs: make sphinx-build be quiet by default

PATCH Superseded Daniel P. Berrangé 2 participants 5 messages Aug 10, 2021 Arm/Amlogic Meson SoC support

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: make sphinx-build be quiet by default

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.

---
 docs/meson.build | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
docs/meson.build +4 -3
index 300b134329..29e119a3cc 100644
@@ -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)
Signature · 1 line
2.31.1
#1 lore raw
Quoted 26 lines · 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.

---
 docs/meson.build | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
docs/meson.build +1 -1
index 300b134329..29e119a3cc 100644
@@ -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,

docs/meson.build if build_docs · line 106

Quoted 10 lines
docs/meson.build +3 -2
                               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

#2 lore raw
Quoted 35 lines · Peter Maydell
Quoted 34 lines · 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.

---
 docs/meson.build | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
docs/meson.build +4 -3
index 300b134329..29e119a3cc 100644
@@ -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()])
 
Quoted 5 lines

docs/meson.build if build_docs · line 106

Quoted 2 lines
docs/meson.build +0 -0
   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

Signature · 3 lines
|: 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 :|
#3 lore raw
Quoted 8 lines · Daniel P. Berrangé
Quoted 2 lines · Peter Maydell

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

#4 lore raw
Quoted 6 lines · Peter Maydell
Quoted 5 lines · Daniel P. Berrangé
Quoted 2 lines · Peter Maydell

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 ?

Quoted 8 lines
Quoted 3 lines

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

Signature · 3 lines
|: 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 :|