[1/4] doc/api: hide verbose doxygen standard output

  The standard output of doxygen is very verbose, and since ninja mixes
stdout and stderr together it makes it difficult to see any warnings from
the doxygen run. Therefore, we can just log the standard output to file,
and only output the stderr to make warnings clear.

Suggested-by: Thomas Monjalon <thomas@monjalon.net>
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/api/generate_doxygen.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
  

> The standard output of doxygen is very verbose, and since ninja mixes
> stdout and stderr together it makes it difficult to see any warnings from
> the doxygen run. Therefore, we can just log the standard output to file,
> and only output the stderr to make warnings clear.
[...]
> -doxygen "${DOXYCONF}" | tee doxygen.out
> +doxygen "${DOXYCONF}" > doxygen.out

ninja is printing extra lines:
	ninja: Entering directory `build'
	[0/1] Running external command doc
	Building docs: Doxygen_API HTML_Guides

It makes hard to detect whether all run fine or not.
Can we remove these extra lines with a ninja option?
Can we return an error if there are some errors in doxygen?
  

On Tue, Sep 29, 2020 at 05:55:44PM +0200, Thomas Monjalon wrote:
> > The standard output of doxygen is very verbose, and since ninja mixes
> > stdout and stderr together it makes it difficult to see any warnings from
> > the doxygen run. Therefore, we can just log the standard output to file,
> > and only output the stderr to make warnings clear.
> [...]
> > -doxygen "${DOXYCONF}" | tee doxygen.out
> > +doxygen "${DOXYCONF}" > doxygen.out
> 
> ninja is printing extra lines:
> 	ninja: Entering directory `build'
> 	[0/1] Running external command doc
> 	Building docs: Doxygen_API HTML_Guides
> 
> It makes hard to detect whether all run fine or not.
> Can we remove these extra lines with a ninja option?
> Can we return an error if there are some errors in doxygen?
> 
If doxygen fails, then the whole build should fail - though to be honest
that is hard to test since most invalid changes I've tried making end up
just as warnings. The wrapper script for doxygen has "-e" flag so it should
fail if any part of it does, i.e. doxygen, and ninja always returns error
if any subtask fails.

There is also the WARN_AS_ERROR setting for doxygen which we can use if you
want to be stricter [1]. Once all warnings are fixed, I'd suggest setting
that based on the werror setting for the build as a whole.

[1] https://www.doxygen.nl/manual/config.html#cfg_warn_as_error
  

29/09/2020 18:23, Bruce Richardson:
> On Tue, Sep 29, 2020 at 05:55:44PM +0200, Thomas Monjalon wrote:
> > > The standard output of doxygen is very verbose, and since ninja mixes
> > > stdout and stderr together it makes it difficult to see any warnings from
> > > the doxygen run. Therefore, we can just log the standard output to file,
> > > and only output the stderr to make warnings clear.
> > [...]
> > > -doxygen "${DOXYCONF}" | tee doxygen.out
> > > +doxygen "${DOXYCONF}" > doxygen.out
> > 
> > ninja is printing extra lines:
> > 	ninja: Entering directory `build'
> > 	[0/1] Running external command doc
> > 	Building docs: Doxygen_API HTML_Guides
> > 
> > It makes hard to detect whether all run fine or not.
> > Can we remove these extra lines with a ninja option?
> > Can we return an error if there are some errors in doxygen?
> > 
> If doxygen fails, then the whole build should fail - though to be honest
> that is hard to test since most invalid changes I've tried making end up
> just as warnings. The wrapper script for doxygen has "-e" flag so it should
> fail if any part of it does, i.e. doxygen, and ninja always returns error
> if any subtask fails.
> 
> There is also the WARN_AS_ERROR setting for doxygen which we can use if you
> want to be stricter [1]. Once all warnings are fixed, I'd suggest setting
> that based on the werror setting for the build as a whole.
> 
> [1] https://www.doxygen.nl/manual/config.html#cfg_warn_as_error

Yes good idea.
Can we make WARN_AS_ERROR depending on the meson option -werror?
  

On Tue, Sep 29, 2020 at 06:31:49PM +0200, Thomas Monjalon wrote:
> 29/09/2020 18:23, Bruce Richardson:
> > On Tue, Sep 29, 2020 at 05:55:44PM +0200, Thomas Monjalon wrote:
> > > > The standard output of doxygen is very verbose, and since ninja mixes
> > > > stdout and stderr together it makes it difficult to see any warnings from
> > > > the doxygen run. Therefore, we can just log the standard output to file,
> > > > and only output the stderr to make warnings clear.
> > > [...]
> > > > -doxygen "${DOXYCONF}" | tee doxygen.out
> > > > +doxygen "${DOXYCONF}" > doxygen.out
> > > 
> > > ninja is printing extra lines:
> > > 	ninja: Entering directory `build'
> > > 	[0/1] Running external command doc
> > > 	Building docs: Doxygen_API HTML_Guides
> > > 
> > > It makes hard to detect whether all run fine or not.
> > > Can we remove these extra lines with a ninja option?
> > > Can we return an error if there are some errors in doxygen?
> > > 
> > If doxygen fails, then the whole build should fail - though to be honest
> > that is hard to test since most invalid changes I've tried making end up
> > just as warnings. The wrapper script for doxygen has "-e" flag so it should
> > fail if any part of it does, i.e. doxygen, and ninja always returns error
> > if any subtask fails.
> > 
> > There is also the WARN_AS_ERROR setting for doxygen which we can use if you
> > want to be stricter [1]. Once all warnings are fixed, I'd suggest setting
> > that based on the werror setting for the build as a whole.
> > 
> > [1] https://www.doxygen.nl/manual/config.html#cfg_warn_as_error
> 
> Yes good idea.
> Can we make WARN_AS_ERROR depending on the meson option -werror?
> 
Yes, very easily, because the doxygen config file is adjustable from meson.
If you want I can do a v2 with a fix for doxygen ethdev and the setting for
WARN_AS_ERROR added as extra patches to this.