DPDK patches and discussions
 help / color / mirror / Atom feed
* [dpdk-dev] [PATCH 0/4] improve output when building docs
@ 2020-09-29 15:34 Bruce Richardson
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output Bruce Richardson
                   ` (4 more replies)
  0 siblings, 5 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 15:34 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

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)

Bruce Richardson (4):
  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

 buildtools/call-sphinx-build.py | 6 ++++--
 doc/api/generate_doxygen.sh     | 6 ++++--
 doc/api/meson.build             | 6 +++---
 3 files changed, 11 insertions(+), 7 deletions(-)

-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output
  2020-09-29 15:34 [dpdk-dev] [PATCH 0/4] improve output when building docs Bruce Richardson
@ 2020-09-29 15:34 ` Bruce Richardson
  2020-09-29 15:55   ` Thomas Monjalon
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 2/4] doc/api: align output folder with sphinx guides Bruce Richardson
                   ` (3 subsequent siblings)
  4 siblings, 1 reply; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 15:34 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

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

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
index ee509e896..b4d66eb15 100755
--- a/doc/api/generate_doxygen.sh
+++ b/doc/api/generate_doxygen.sh
@@ -7,7 +7,7 @@ OUTDIR=$2
 SCRIPTCSS=$3
 
 # run doxygen, capturing all the header files it processed
-doxygen "${DOXYCONF}" | tee doxygen.out
+doxygen "${DOXYCONF}" > doxygen.out
 echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' doxygen.out)" > $OUTDIR.d
 
 "${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH 2/4] doc/api: align output folder with sphinx guides
  2020-09-29 15:34 [dpdk-dev] [PATCH 0/4] improve output when building docs Bruce Richardson
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output Bruce Richardson
@ 2020-09-29 15:34 ` Bruce Richardson
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 3/4] doc/api: put output log file in build directory Bruce Richardson
                   ` (2 subsequent siblings)
  4 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 15:34 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

The API docs were output to "<build>/doc/api/api" folder, which was
ugly-looking with the repeated "api", and inconsistent with the sphinx
guides which were written to "<build>/doc/guides/html". Changing the doxgen
output folder to "html" fixes both these issues.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/api/meson.build | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/api/meson.build b/doc/api/meson.build
index 49d5b9a15..e9b49f9c2 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -34,7 +34,7 @@ cdata = configuration_data()
 cdata.set('VERSION', meson.project_version())
 cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
 cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
-cdata.set('HTML_OUTPUT', 'api')
+cdata.set('HTML_OUTPUT', 'html')
 cdata.set('TOPDIR', meson.source_root())
 cdata.set('STRIP_FROM_PATH', meson.source_root())
 
@@ -45,8 +45,8 @@ doxy_conf = configure_file(input: 'doxy-api.conf.in',
 doxy_build = custom_target('doxygen',
 	depends: example,
 	input: doxy_conf,
-	output: 'api',
-	depfile: 'api.d',
+	output: 'html',
+	depfile: 'html.d',
 	command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
 	install: get_option('enable_docs'),
 	install_dir: htmldir,
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH 3/4] doc/api: put output log file in build directory
  2020-09-29 15:34 [dpdk-dev] [PATCH 0/4] improve output when building docs Bruce Richardson
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output Bruce Richardson
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 2/4] doc/api: align output folder with sphinx guides Bruce Richardson
@ 2020-09-29 15:34 ` Bruce Richardson
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 4/4] doc/guides: suppress printing out standard output Bruce Richardson
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
  4 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 15:34 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

The meson documentation states that projects should not rely upon the
custom_target build commands are run from any given directory.  Therefore,
rather than writing the standout output from doxygen to the current
directory - which could be anywhere in future, put it into the api
directory, so that it is in a known location.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/api/generate_doxygen.sh | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
index b4d66eb15..1350e5049 100755
--- a/doc/api/generate_doxygen.sh
+++ b/doc/api/generate_doxygen.sh
@@ -6,8 +6,10 @@ DOXYCONF=$1
 OUTDIR=$2
 SCRIPTCSS=$3
 
+OUT_FILE=$(dirname $OUTDIR)/doxygen.out
+
 # run doxygen, capturing all the header files it processed
-doxygen "${DOXYCONF}" > doxygen.out
-echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' doxygen.out)" > $OUTDIR.d
+doxygen "${DOXYCONF}" > $OUT_FILE
+echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' $OUT_FILE)" > $OUTDIR.d
 
 "${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH 4/4] doc/guides: suppress printing out standard output
  2020-09-29 15:34 [dpdk-dev] [PATCH 0/4] improve output when building docs Bruce Richardson
                   ` (2 preceding siblings ...)
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 3/4] doc/api: put output log file in build directory Bruce Richardson
@ 2020-09-29 15:34 ` Bruce Richardson
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
  4 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 15:34 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

To see only errors and warnings from the doc builds, we can send the
standard output text to a logfile and have only the stderr messages
printed. This is similar to what is done for the API documentation.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 buildtools/call-sphinx-build.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
index fa6f26b37..0dce59f64 100755
--- a/buildtools/call-sphinx-build.py
+++ b/buildtools/call-sphinx-build.py
@@ -27,8 +27,10 @@
     srcfiles.extend([join(root, f) for f in files])
 
 # run sphinx, putting the html output in a "html" directory
-process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')], check=True)
-print(str(process.args) + ' Done OK')
+with open(join(dst, 'sphinx_html.out'), 'w') as out:
+    process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')],
+                  check=True,
+                  stdout=out)
 
 # create a gcc format .d file giving all the dependencies of this doc build
 with open(join(dst, '.html.d'), 'w') as d:
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output Bruce Richardson
@ 2020-09-29 15:55   ` Thomas Monjalon
  2020-09-29 16:23     ` Bruce Richardson
  0 siblings, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-09-29 15:55 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev

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




^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output
  2020-09-29 15:55   ` Thomas Monjalon
@ 2020-09-29 16:23     ` Bruce Richardson
  2020-09-29 16:31       ` Thomas Monjalon
  0 siblings, 1 reply; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:23 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev

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

^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output
  2020-09-29 16:23     ` Bruce Richardson
@ 2020-09-29 16:31       ` Thomas Monjalon
  2020-09-29 16:40         ` Bruce Richardson
  0 siblings, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-09-29 16:31 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev

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?





^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output
  2020-09-29 16:31       ` Thomas Monjalon
@ 2020-09-29 16:40         ` Bruce Richardson
  0 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:40 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev

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.

^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 0/6] improve building docs
  2020-09-29 15:34 [dpdk-dev] [PATCH 0/4] improve output when building docs Bruce Richardson
                   ` (3 preceding siblings ...)
  2020-09-29 15:34 ` [dpdk-dev] [PATCH 4/4] doc/guides: suppress printing out standard output Bruce Richardson
@ 2020-09-29 16:54 ` Bruce Richardson
  2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 1/6] doc/api: hide verbose doxygen standard output Bruce Richardson
                     ` (6 more replies)
  4 siblings, 7 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:54 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

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

-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 1/6] doc/api: hide verbose doxygen standard output
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
@ 2020-09-29 16:54   ` Bruce Richardson
  2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 2/6] doc/api: align output folder with sphinx guides Bruce Richardson
                     ` (5 subsequent siblings)
  6 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:54 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

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

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
index ee509e896..b4d66eb15 100755
--- a/doc/api/generate_doxygen.sh
+++ b/doc/api/generate_doxygen.sh
@@ -7,7 +7,7 @@ OUTDIR=$2
 SCRIPTCSS=$3
 
 # run doxygen, capturing all the header files it processed
-doxygen "${DOXYCONF}" | tee doxygen.out
+doxygen "${DOXYCONF}" > doxygen.out
 echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' doxygen.out)" > $OUTDIR.d
 
 "${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 2/6] doc/api: align output folder with sphinx guides
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
  2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 1/6] doc/api: hide verbose doxygen standard output Bruce Richardson
@ 2020-09-29 16:54   ` Bruce Richardson
  2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 3/6] doc/api: put output log file in build directory Bruce Richardson
                     ` (4 subsequent siblings)
  6 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:54 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

The API docs were output to "<build>/doc/api/api" folder, which was
ugly-looking with the repeated "api", and inconsistent with the sphinx
guides which were written to "<build>/doc/guides/html". Changing the
doxygen output folder to "html" fixes both these issues.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/api/meson.build | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/api/meson.build b/doc/api/meson.build
index 49d5b9a15..e9b49f9c2 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -34,7 +34,7 @@ cdata = configuration_data()
 cdata.set('VERSION', meson.project_version())
 cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
 cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
-cdata.set('HTML_OUTPUT', 'api')
+cdata.set('HTML_OUTPUT', 'html')
 cdata.set('TOPDIR', meson.source_root())
 cdata.set('STRIP_FROM_PATH', meson.source_root())
 
@@ -45,8 +45,8 @@ doxy_conf = configure_file(input: 'doxy-api.conf.in',
 doxy_build = custom_target('doxygen',
 	depends: example,
 	input: doxy_conf,
-	output: 'api',
-	depfile: 'api.d',
+	output: 'html',
+	depfile: 'html.d',
 	command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
 	install: get_option('enable_docs'),
 	install_dir: htmldir,
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 3/6] doc/api: put output log file in build directory
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
  2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 1/6] doc/api: hide verbose doxygen standard output Bruce Richardson
  2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 2/6] doc/api: align output folder with sphinx guides Bruce Richardson
@ 2020-09-29 16:54   ` Bruce Richardson
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 4/6] doc/guides: suppress printing out standard output Bruce Richardson
                     ` (3 subsequent siblings)
  6 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:54 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

The meson documentation states that projects should not rely upon the
custom_target build commands are run from any given directory.  Therefore,
rather than writing the standout output from doxygen to the current
directory - which could be anywhere in future, put it into the api
directory, so that it is in a known location.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/api/generate_doxygen.sh | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
index b4d66eb15..1350e5049 100755
--- a/doc/api/generate_doxygen.sh
+++ b/doc/api/generate_doxygen.sh
@@ -6,8 +6,10 @@ DOXYCONF=$1
 OUTDIR=$2
 SCRIPTCSS=$3
 
+OUT_FILE=$(dirname $OUTDIR)/doxygen.out
+
 # run doxygen, capturing all the header files it processed
-doxygen "${DOXYCONF}" > doxygen.out
-echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' doxygen.out)" > $OUTDIR.d
+doxygen "${DOXYCONF}" > $OUT_FILE
+echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' $OUT_FILE)" > $OUTDIR.d
 
 "${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 4/6] doc/guides: suppress printing out standard output
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
                     ` (2 preceding siblings ...)
  2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 3/6] doc/api: put output log file in build directory Bruce Richardson
@ 2020-09-29 16:55   ` Bruce Richardson
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter Bruce Richardson
                     ` (2 subsequent siblings)
  6 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:55 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

To see only errors and warnings from the doc builds, we can send the
standard output text to a logfile and have only the stderr messages
printed. This is similar to what is done for the API documentation.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 buildtools/call-sphinx-build.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
index fa6f26b37..0dce59f64 100755
--- a/buildtools/call-sphinx-build.py
+++ b/buildtools/call-sphinx-build.py
@@ -27,8 +27,10 @@
     srcfiles.extend([join(root, f) for f in files])
 
 # run sphinx, putting the html output in a "html" directory
-process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')], check=True)
-print(str(process.args) + ' Done OK')
+with open(join(dst, 'sphinx_html.out'), 'w') as out:
+    process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')],
+                  check=True,
+                  stdout=out)
 
 # create a gcc format .d file giving all the dependencies of this doc build
 with open(join(dst, '.html.d'), 'w') as d:
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
                     ` (3 preceding siblings ...)
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 4/6] doc/guides: suppress printing out standard output Bruce Richardson
@ 2020-09-29 16:55   ` Bruce Richardson
  2020-09-29 17:34     ` David Marchand
  2020-09-29 17:34     ` Thomas Monjalon
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 6/6] doc/api: make doc warnings errors when werror option set Bruce Richardson
  2020-09-30 14:32   ` [dpdk-dev] [PATCH v2 0/6] improve building docs Thomas Monjalon
  6 siblings, 2 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:55 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson, i.dyukov

The parameter to rte_eth_link_speed_to_str was called "speed_link" in the
function prototype in the header file, but "link_speed" everywhere else.
This showed up as warnings when building the API docs, due to missing and
undocumented parameters from doxygen's viewpoint.

Rename the prototype value to the correct name to fix these issues.

Fixes: fbf931c9c392 ("ethdev: format link status text")
Cc: i.dyukov@samsung.com

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 lib/librte_ethdev/rte_ethdev.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/librte_ethdev/rte_ethdev.h b/lib/librte_ethdev/rte_ethdev.h
index 645a18664..9759f1330 100644
--- a/lib/librte_ethdev/rte_ethdev.h
+++ b/lib/librte_ethdev/rte_ethdev.h
@@ -2452,7 +2452,7 @@ int rte_eth_link_get_nowait(uint16_t port_id, struct rte_eth_link *link);
  *   No free is required.
  */
 __rte_experimental
-const char *rte_eth_link_speed_to_str(uint32_t speed_link);
+const char *rte_eth_link_speed_to_str(uint32_t link_speed);
 
 /**
  * @warning
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* [dpdk-dev] [PATCH v2 6/6] doc/api: make doc warnings errors when werror option set
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
                     ` (4 preceding siblings ...)
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter Bruce Richardson
@ 2020-09-29 16:55   ` Bruce Richardson
  2020-09-29 17:33     ` Thomas Monjalon
  2020-09-30 14:32   ` [dpdk-dev] [PATCH v2 0/6] improve building docs Thomas Monjalon
  6 siblings, 1 reply; 21+ messages in thread
From: Bruce Richardson @ 2020-09-29 16:55 UTC (permalink / raw)
  To: dev; +Cc: thomas, Bruce Richardson

When the --werror meson build option is set, we can set the WARN_AS_ERRORS
doxygen option in the doxygen config flag to get the same behaviour for API
doc building as for building the rest of DPDK. This can help catch
documentation errors sooner in the development process.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/api/doxy-api.conf.in | 1 +
 doc/api/meson.build      | 4 ++++
 2 files changed, 5 insertions(+)

diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index 42d38919d..9182ee852 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -89,6 +89,7 @@ HIDE_SCOPE_NAMES        = YES
 GENERATE_DEPRECATEDLIST = YES
 VERBATIM_HEADERS        = NO
 ALPHABETICAL_INDEX      = NO
+WARN_AS_ERROR           = @WARN_AS_ERROR@
 
 HTML_TIMESTAMP          = NO
 HTML_DYNAMIC_SECTIONS   = YES
diff --git a/doc/api/meson.build b/doc/api/meson.build
index e9b49f9c2..4f51f5d72 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -37,6 +37,10 @@ cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
 cdata.set('HTML_OUTPUT', 'html')
 cdata.set('TOPDIR', meson.source_root())
 cdata.set('STRIP_FROM_PATH', meson.source_root())
+cdata.set('WARN_AS_ERROR', 'NO')
+if get_option('werror')
+	cdata.set('WARN_AS_ERROR', 'YES')
+endif
 
 doxy_conf = configure_file(input: 'doxy-api.conf.in',
 	output: 'doxy-api.conf',
-- 
2.25.1


^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v2 6/6] doc/api: make doc warnings errors when werror option set
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 6/6] doc/api: make doc warnings errors when werror option set Bruce Richardson
@ 2020-09-29 17:33     ` Thomas Monjalon
  0 siblings, 0 replies; 21+ messages in thread
From: Thomas Monjalon @ 2020-09-29 17:33 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev

--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -89,6 +89,7 @@ HIDE_SCOPE_NAMES        = YES
 GENERATE_DEPRECATEDLIST = YES
 VERBATIM_HEADERS        = NO
 ALPHABETICAL_INDEX      = NO
+WARN_AS_ERROR           = @WARN_AS_ERROR@

This section is about the appearance of the output.
I think this new "warning" option would better fit at the end of the file.



^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter Bruce Richardson
@ 2020-09-29 17:34     ` David Marchand
  2020-09-29 17:34     ` Thomas Monjalon
  1 sibling, 0 replies; 21+ messages in thread
From: David Marchand @ 2020-09-29 17:34 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev, Thomas Monjalon, Ivan Dyukov

On Tue, Sep 29, 2020 at 6:57 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> The parameter to rte_eth_link_speed_to_str was called "speed_link" in the
> function prototype in the header file, but "link_speed" everywhere else.
> This showed up as warnings when building the API docs, due to missing and
> undocumented parameters from doxygen's viewpoint.
>
> Rename the prototype value to the correct name to fix these issues.
>
> Fixes: fbf931c9c392 ("ethdev: format link status text")
> Cc: i.dyukov@samsung.com
>
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

Already fixed with:
https://git.dpdk.org/next/dpdk-next-net/commit/?id=10c835f2f57a62e50c83c764926d2481afbb60d5


-- 
David Marchand


^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter Bruce Richardson
  2020-09-29 17:34     ` David Marchand
@ 2020-09-29 17:34     ` Thomas Monjalon
  2020-09-30  9:01       ` Bruce Richardson
  1 sibling, 1 reply; 21+ messages in thread
From: Thomas Monjalon @ 2020-09-29 17:34 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev, i.dyukov

> The parameter to rte_eth_link_speed_to_str was called "speed_link" in the
> function prototype in the header file, but "link_speed" everywhere else.
> This showed up as warnings when building the API docs, due to missing and
> undocumented parameters from doxygen's viewpoint.
> 
> Rename the prototype value to the correct name to fix these issues.

It has been fixed by David and merged already by Ferruh.



^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter
  2020-09-29 17:34     ` Thomas Monjalon
@ 2020-09-30  9:01       ` Bruce Richardson
  0 siblings, 0 replies; 21+ messages in thread
From: Bruce Richardson @ 2020-09-30  9:01 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev, i.dyukov

On Tue, Sep 29, 2020 at 07:34:17PM +0200, Thomas Monjalon wrote:
> > The parameter to rte_eth_link_speed_to_str was called "speed_link" in
> > the function prototype in the header file, but "link_speed" everywhere
> > else.  This showed up as warnings when building the API docs, due to
> > missing and undocumented parameters from doxygen's viewpoint.
> > 
> > Rename the prototype value to the correct name to fix these issues.
> 
> It has been fixed by David and merged already by Ferruh.
> 
Yep, I guessed there was a patch outstanding for it from someone, though I
think the patch wasn't merged when I did this patch, so I included it to
guarantee that this patchset didn't break the build when werror was turned
on.

/Bruce

^ permalink raw reply	[flat|nested] 21+ messages in thread

* Re: [dpdk-dev] [PATCH v2 0/6] improve building docs
  2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
                     ` (5 preceding siblings ...)
  2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 6/6] doc/api: make doc warnings errors when werror option set Bruce Richardson
@ 2020-09-30 14:32   ` Thomas Monjalon
  6 siblings, 0 replies; 21+ messages in thread
From: Thomas Monjalon @ 2020-09-30 14:32 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev

> 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



^ permalink raw reply	[flat|nested] 21+ messages in thread

end of thread, other threads:[~2020-09-30 14:32 UTC | newest]

Thread overview: 21+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-09-29 15:34 [dpdk-dev] [PATCH 0/4] improve output when building docs Bruce Richardson
2020-09-29 15:34 ` [dpdk-dev] [PATCH 1/4] doc/api: hide verbose doxygen standard output Bruce Richardson
2020-09-29 15:55   ` Thomas Monjalon
2020-09-29 16:23     ` Bruce Richardson
2020-09-29 16:31       ` Thomas Monjalon
2020-09-29 16:40         ` Bruce Richardson
2020-09-29 15:34 ` [dpdk-dev] [PATCH 2/4] doc/api: align output folder with sphinx guides Bruce Richardson
2020-09-29 15:34 ` [dpdk-dev] [PATCH 3/4] doc/api: put output log file in build directory Bruce Richardson
2020-09-29 15:34 ` [dpdk-dev] [PATCH 4/4] doc/guides: suppress printing out standard output Bruce Richardson
2020-09-29 16:54 ` [dpdk-dev] [PATCH v2 0/6] improve building docs Bruce Richardson
2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 1/6] doc/api: hide verbose doxygen standard output Bruce Richardson
2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 2/6] doc/api: align output folder with sphinx guides Bruce Richardson
2020-09-29 16:54   ` [dpdk-dev] [PATCH v2 3/6] doc/api: put output log file in build directory Bruce Richardson
2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 4/6] doc/guides: suppress printing out standard output Bruce Richardson
2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 5/6] ethdev: fix mis-named parameter Bruce Richardson
2020-09-29 17:34     ` David Marchand
2020-09-29 17:34     ` Thomas Monjalon
2020-09-30  9:01       ` Bruce Richardson
2020-09-29 16:55   ` [dpdk-dev] [PATCH v2 6/6] doc/api: make doc warnings errors when werror option set Bruce Richardson
2020-09-29 17:33     ` Thomas Monjalon
2020-09-30 14:32   ` [dpdk-dev] [PATCH v2 0/6] improve building docs Thomas Monjalon

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).