Skip to content

improve building docs

Bruce Richardson dpdk-dev 2 versions In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v2 Latest6 patches 5 repliesIn review
  2. v14 patches 4 repliesSuperseded

Patches in v2 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/6doc/api: hide verbose doxygen standard outputdoc/api/generate_doxygen.sh+1 -10 replies
2/6doc/api: align output folder with sphinx guidesdoc/api/meson.build+3 -30 replies
3/6doc/api: put output log file in build directorydoc/api/generate_doxygen.sh+4 -20 replies
4/6doc/guides: suppress printing out standard outputbuildtools/call-sphinx-build.py+4 -20 replies
5/6ethdev: fix mis-named parameterlib/librte_ethdev/rte_ethdev.h+1 -13 replies
6/6doc/api: make doc warnings errors when werror option setdoc/api/doxy-api.conf.in doc/api/meson.build+5 -01 reply

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v2 yet.

Read the v2 thread

Cover letter [dpdk-dev] [PATCH v2 0/6] improve building docs

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(-)
Signature · 1 line
2.25.1