mbox series

[v2,0/6] improve building docs

Message ID 20200929165502.336919-1-bruce.richardson@intel.com (mailing list archive)
Headers
Series improve building docs |

Message

Bruce Richardson Sept. 29, 2020, 4:54 p.m. UTC 
  When building the documentation, a lot of text is output, meaning that
any warnings can be missed in all the text. Unfortunately, ninja merges
both stderr and stdout of all tasks so one cannot just redirect stdout to
a separate location as part of the build command to rectify that.
Therefore, since we rarely care about the output of the doc builds, only
output the stderr text and write the standard output text to a log file
in the relevant build folder (i.e. build/doc/guides or build/doc/api)

Related to this, we can catch documentation bugs earlier by setting
WARN_AS_ERRORS for doxygen, meaning the build will fail if any API
documentation warnings as encountered. Rather than setting this globally,
we can link it to the global build --werror setting.

---
V2: added in patches to fix API doc issue, and enable WARN_AS_ERRORS

Bruce Richardson (6):
  doc/api: hide verbose doxygen standard output
  doc/api: align output folder with sphinx guides
  doc/api: put output log file in build directory
  doc/guides: suppress printing out standard output
  ethdev: fix mis-named parameter
  doc/api: make doc warnings errors when werror option set

 buildtools/call-sphinx-build.py |  6 ++++--
 doc/api/doxy-api.conf.in        |  1 +
 doc/api/generate_doxygen.sh     |  6 ++++--
 doc/api/meson.build             | 10 +++++++---
 lib/librte_ethdev/rte_ethdev.h  |  2 +-
 5 files changed, 17 insertions(+), 8 deletions(-)

Comments

Thomas Monjalon Sept. 30, 2020, 2:32 p.m. UTC | #1 
> When building the documentation, a lot of text is output, meaning that
> any warnings can be missed in all the text. Unfortunately, ninja merges
> both stderr and stdout of all tasks so one cannot just redirect stdout to
> a separate location as part of the build command to rectify that.
> Therefore, since we rarely care about the output of the doc builds, only
> output the stderr text and write the standard output text to a log file
> in the relevant build folder (i.e. build/doc/guides or build/doc/api)
> 
> Related to this, we can catch documentation bugs earlier by setting
> WARN_AS_ERRORS for doxygen, meaning the build will fail if any API
> documentation warnings as encountered. Rather than setting this globally,
> we can link it to the global build --werror setting.

Applied with suggested minor change, and without ethdev fix. Thanks