[PATCH dpdk] meson: properly disable docs

[PATCH dpdk] meson: properly disable docs

[Robin Jarry]

Fix the following meson warning when -Denable_docs=false:

 $ meson setup build -Denable_docs=false -Denable_drivers=net/null \
      -Denable_libs=rib -Ddisable_apps=* --wipe --fatal-meson-warnings
 ...
 Program doxygen found: YES (/usr/bin/doxygen)
 Configuring doxy-api-html.conf using configuration
 doc/api/meson.build:54: WARNING: The variable(s) 'DTS_API_MAIN_PAGE' in
 the input file 'doc/api/doxy-api.conf.in' are not present in the given
 configuration data.
 doc/api/meson.build:54:17: ERROR: Fatal warnings enabled, aborting

When -Denable_docs=false, do not even enter the doc subdir. Replace all
occurrences of get_option('enable_docs') in the doc subdir with true.

Fixes: 7f9326423a04 ("dts: add API doc generation")
Signed-off-by: Robin Jarry <rjarry@redhat.com>
---
 doc/api/dts/meson.build |  6 +++---
 doc/api/meson.build     | 16 ++++++++--------
 doc/guides/meson.build  |  6 +++---
 meson.build             |  6 ++++--
 4 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/doc/api/dts/meson.build b/doc/api/dts/meson.build
index 5115df70956b..a8edd232ddcf 100644
--- a/doc/api/dts/meson.build
+++ b/doc/api/dts/meson.build
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright(c) 2023 PANTHEON.tech s.r.o.
 
-sphinx = find_program('sphinx-build', required: get_option('enable_docs'))
+sphinx = find_program('sphinx-build', required: true)
 if not sphinx.found()
     subdir_done()
 endif
@@ -23,8 +23,8 @@ dts_api_html = custom_target('dts_api_html',
         output: 'html',
         command: [sphinx_wrapper, sphinx, meson.project_version(),
             meson.current_source_dir(), meson.current_build_dir(), extra_sphinx_args],
-        build_by_default: get_option('enable_docs'),
-        install: get_option('enable_docs'),
+        build_by_default: true,
+        install: true,
         install_dir: htmldir)
 
 doc_targets += dts_api_html
diff --git a/doc/api/meson.build b/doc/api/meson.build
index ae23e9825edc..d82803df388d 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
 
-doxygen = find_program('doxygen', required: get_option('enable_docs'))
+doxygen = find_program('doxygen', required: true)
 
 if not doxygen.found()
   # process DTS API doc build even if DPDK API doc build can't be done
@@ -28,9 +28,9 @@ example = custom_target('examples.dox',
         output: 'examples.dox',
         command: [generate_examples, join_paths(dpdk_source_root, 'examples'), '@OUTPUT@'],
         depfile: 'examples.dox.d',
-        install: get_option('enable_docs'),
+        install: true,
         install_dir: htmldir,
-        build_by_default: get_option('enable_docs'))
+        build_by_default: true)
 
 # set up common Doxygen configuration
 cdata = configuration_data()
@@ -76,9 +76,9 @@ doxy_html_build = custom_target('doxygen-html',
         output: 'html',
         depfile: 'html.d',
         command: [generate_doxygen, '@OUTPUT@', doxygen, '@INPUT@'],
-        install: get_option('enable_docs'),
+        install: true,
         install_dir: htmldir,
-        build_by_default: get_option('enable_docs'))
+        build_by_default: true)
 
 doc_targets += doxy_html_build
 doc_target_names += 'Doxygen_API(HTML)'
@@ -90,9 +90,9 @@ doxy_man_build = custom_target('doxygen-man',
         output: 'man',
         depfile: 'man.d',
         command: [generate_doxygen, '@OUTPUT@', doxygen, '@INPUT@'],
-        install: get_option('enable_docs'),
+        install: true,
         install_dir: get_option('datadir'),
-        build_by_default: get_option('enable_docs'))
+        build_by_default: true)
 
 doc_targets += doxy_man_build
 doc_target_names += 'Doxygen_API(Manpage)'
@@ -100,7 +100,7 @@ doc_target_names += 'Doxygen_API(Manpage)'
 # refresh the manpage database on install
 # if DPDK manpages are installed to a staging directory, not in MANPATH, this has no effect
 mandb = find_program('mandb', required: false)
-if mandb.found() and get_option('enable_docs')
+if mandb.found()
     meson.add_install_script(mandb)
 endif
 
diff --git a/doc/guides/meson.build b/doc/guides/meson.build
index f8bbfba9f5b5..840f9c8a6bfb 100644
--- a/doc/guides/meson.build
+++ b/doc/guides/meson.build
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright(c) 2018 Intel Corporation
 
-sphinx = find_program('sphinx-build', required: get_option('enable_docs'))
+sphinx = find_program('sphinx-build', required: true)
 
 if not sphinx.found()
     subdir_done()
@@ -20,8 +20,8 @@ html_guides = custom_target('html_guides',
             meson.current_source_dir(), meson.current_build_dir(),
             extra_sphinx_args],
         depfile: '.html.d',
-        build_by_default: get_option('enable_docs'),
-        install: get_option('enable_docs'),
+        build_by_default: true,
+        install: true,
         install_dir: htmldir)
 
 doc_targets += html_guides
diff --git a/meson.build b/meson.build
index fe9040369ab9..d67d5577a1d4 100644
--- a/meson.build
+++ b/meson.build
@@ -82,8 +82,10 @@ subdir('drivers')
 subdir('usertools')
 subdir('app')
 
-# build docs
-subdir('doc')
+if get_option('enable_docs')
+    # build docs
+    subdir('doc')
+endif
 
 # build any examples explicitly requested - useful for developers - and
 # install any example code into the appropriate install path
-- 
2.47.0

Re: [PATCH dpdk] meson: properly disable docs

[Bruce Richardson]

On Tue, Oct 22, 2024 at 05:11:42PM +0200, Robin Jarry wrote:
> Fix the following meson warning when -Denable_docs=false:
> 
>  $ meson setup build -Denable_docs=false -Denable_drivers=net/null \
>       -Denable_libs=rib -Ddisable_apps=* --wipe --fatal-meson-warnings
>  ...
>  Program doxygen found: YES (/usr/bin/doxygen)
>  Configuring doxy-api-html.conf using configuration
>  doc/api/meson.build:54: WARNING: The variable(s) 'DTS_API_MAIN_PAGE' in
>  the input file 'doc/api/doxy-api.conf.in' are not present in the given
>  configuration data.
>  doc/api/meson.build:54:17: ERROR: Fatal warnings enabled, aborting
> 
> When -Denable_docs=false, do not even enter the doc subdir. Replace all
> occurrences of get_option('enable_docs') in the doc subdir with true.
> 
> Fixes: 7f9326423a04 ("dts: add API doc generation")
> Signed-off-by: Robin Jarry <rjarry@redhat.com>
> ---
>  doc/api/dts/meson.build |  6 +++---
>  doc/api/meson.build     | 16 ++++++++--------
>  doc/guides/meson.build  |  6 +++---
>  meson.build             |  6 ++++--
>  4 files changed, 18 insertions(+), 16 deletions(-)
> 
No strong objection to this. Just FYI, the reason it is currently done as
it is in the build, is that even if you configure a build without the docs
enabled, you can just build the docs explicitly by doing "ninja -C build
doc". That is so that one can do a test build of the docs without
a) having to reconfigure the whole project
b) not have every build from then on rebuild e.g. the APIs doc if you
change a header.

Regards,
/Bruce

Re: [PATCH dpdk] meson: properly disable docs

[Robin Jarry]

Bruce Richardson, Oct 22, 2024 at 17:25:
> No strong objection to this. Just FYI, the reason it is currently done as
> it is in the build, is that even if you configure a build without the docs
> enabled, you can just build the docs explicitly by doing "ninja -C build
> doc". That is so that one can do a test build of the docs without
> a) having to reconfigure the whole project
> b) not have every build from then on rebuild e.g. the APIs doc if you
> change a header.

Oh, I didn't know it was on purpose. I was surprised to see doc related 
warnings with -Denable_docs=false.

Feel free to disregard this patch if you think it is too drastic.

Re: [PATCH dpdk] meson: properly disable docs

[Stephen Hemminger]

On Tue, 22 Oct 2024 17:11:42 +0200
Robin Jarry <rjarry@redhat.com> wrote:

> Fix the following meson warning when -Denable_docs=false:
> 
>  $ meson setup build -Denable_docs=false -Denable_drivers=net/null \
>       -Denable_libs=rib -Ddisable_apps=* --wipe --fatal-meson-warnings
>  ...
>  Program doxygen found: YES (/usr/bin/doxygen)
>  Configuring doxy-api-html.conf using configuration
>  doc/api/meson.build:54: WARNING: The variable(s) 'DTS_API_MAIN_PAGE' in
>  the input file 'doc/api/doxy-api.conf.in' are not present in the given
>  configuration data.
>  doc/api/meson.build:54:17: ERROR: Fatal warnings enabled, aborting
> 
> When -Denable_docs=false, do not even enter the doc subdir. Replace all
> occurrences of get_option('enable_docs') in the doc subdir with true.
> 
> Fixes: 7f9326423a04 ("dts: add API doc generation")
> Signed-off-by: Robin Jarry <rjarry@redhat.com>

Acked-by: Stephen Hemminger <stephen@networkplumber.org>

Re: [PATCH dpdk] meson: properly disable docs

[Bruce Richardson]

On Tue, Oct 22, 2024 at 05:31:47PM +0200, Robin Jarry wrote:
> Bruce Richardson, Oct 22, 2024 at 17:25:
> > No strong objection to this. Just FYI, the reason it is currently done as
> > it is in the build, is that even if you configure a build without the docs
> > enabled, you can just build the docs explicitly by doing "ninja -C build
> > doc". That is so that one can do a test build of the docs without
> > a) having to reconfigure the whole project
> > b) not have every build from then on rebuild e.g. the APIs doc if you
> > change a header.
> 
> Oh, I didn't know it was on purpose. I was surprised to see doc related
> warnings with -Denable_docs=false.
> 
> Feel free to disregard this patch if you think it is too drastic.
> 
Like I said, I don't have that strong of opinions about it - I just wanted
to let you and others know that there was *some* (however little) method
behind the madness of doing things this way.
It is possible to fix the error directly, so that the warning does not
appear if docs are disabled?

/Bruce

Re: [PATCH dpdk] meson: properly disable docs

[Thomas Monjalon]

22/10/2024 17:49, Bruce Richardson:
> On Tue, Oct 22, 2024 at 05:31:47PM +0200, Robin Jarry wrote:
> > Bruce Richardson, Oct 22, 2024 at 17:25:
> > > No strong objection to this. Just FYI, the reason it is currently done as
> > > it is in the build, is that even if you configure a build without the docs
> > > enabled, you can just build the docs explicitly by doing "ninja -C build
> > > doc". That is so that one can do a test build of the docs without
> > > a) having to reconfigure the whole project
> > > b) not have every build from then on rebuild e.g. the APIs doc if you
> > > change a header.
> > 
> > Oh, I didn't know it was on purpose. I was surprised to see doc related
> > warnings with -Denable_docs=false.
> > 
> > Feel free to disregard this patch if you think it is too drastic.
> > 
> Like I said, I don't have that strong of opinions about it - I just wanted
> to let you and others know that there was *some* (however little) method
> behind the madness of doing things this way.

Let's not change the convenient behaviour.
I reject this patch.

> It is possible to fix the error directly, so that the warning does not
> appear if docs are disabled?

We must fix warnings yes.