From: Luca Boccassi <bluca@debian.org>
To: dev@dpdk.org
Cc: bruce.richardson@intel.com, john.mcnamara@intel.com,
marko.kovacevic@intel.com, thomas@monjalon.net
Subject: [PATCH v4 4/4] build: generate API documentation with Meson
Date: Mon, 10 Sep 2018 21:10:00 +0100 [thread overview]
Message-ID: <20180910201000.11243-4-bluca@debian.org> (raw)
In-Reply-To: <20180910201000.11243-1-bluca@debian.org>
Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v2: made doxygen dependency optional, skip doxygen build when not found
v3: made doxygen dependency mandatory if enable_docs is true, add
alternative doc target that prints "doxygen not found" when doxygen
is not found and enable_docs is false (default)
v4: add acked-by
doc/api/generate_doxygen.sh | 10 +++++++
doc/api/meson.build | 56 +++++++++++++++++++++++++++++++++++++
doc/build-sdk-meson.txt | 2 ++
doc/meson.build | 4 +++
meson.build | 3 ++
meson_options.txt | 2 ++
6 files changed, 77 insertions(+)
create mode 100755 doc/api/generate_doxygen.sh
create mode 100644 doc/api/meson.build
create mode 100644 doc/meson.build
diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
new file mode 100755
index 0000000000..ab57660958
--- /dev/null
+++ b/doc/api/generate_doxygen.sh
@@ -0,0 +1,10 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+DOXYCONF=$1
+OUTDIR=$2
+SCRIPTCSS=$3
+
+doxygen "${DOXYCONF}"
+"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
diff --git a/doc/api/meson.build b/doc/api/meson.build
new file mode 100644
index 0000000000..602fa7f3c3
--- /dev/null
+++ b/doc/api/meson.build
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+doxygen = find_program('doxygen', required: get_option('enable_docs'))
+
+if doxygen.found()
+ # due to the CSS customisation script, which needs to run on a file that
+ # is in a subdirectory that is created at build time and thus it cannot
+ # be an individual custom_target, we need to wrap the doxygen call in a
+ # script to run the CSS modification afterwards
+ generate_doxygen = find_program('generate_doxygen.sh')
+ generate_examples = find_program('generate_examples.sh')
+ generate_css = find_program('doxy-html-custom.sh')
+
+ inputdir = join_paths(meson.source_root(), 'examples')
+ htmldir = join_paths('doc', 'html')
+
+ # due to the following bug: https://github.com/mesonbuild/meson/issues/4107
+ # if install is set to true it will override build_by_default and it will
+ # cause the target to always be built. If install were to be always set to
+ # false it would be impossible to install the docs.
+ # So use a configure option for now.
+ example = custom_target('examples.dox',
+ input: inputdir,
+ output: 'examples.dox',
+ command: [generate_examples, '@INPUT@', '@OUTPUT@'],
+ install: get_option('enable_docs'),
+ install_dir: htmldir,
+ build_by_default: false)
+
+ 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('TOPDIR', meson.source_root())
+ cdata.set('STRIP_FROM_PATH', meson.source_root())
+
+ doxy_conf = configure_file(input: 'doxy-api.conf.in',
+ output: 'doxy-api.conf',
+ configuration: cdata,
+ install: false)
+
+ doxy_build = custom_target('doxygen',
+ depends: example,
+ input: doxy_conf,
+ output: 'api',
+ command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
+ install: get_option('enable_docs'),
+ install_dir: htmldir,
+ build_by_default: false)
+
+ run_target('doc', command: 'true', depends: doxy_build)
+else
+ run_target('doc', command: ['echo', 'doxygen', 'not', 'found'])
+endif
diff --git a/doc/build-sdk-meson.txt b/doc/build-sdk-meson.txt
index 9618e759ea..508e2cb642 100644
--- a/doc/build-sdk-meson.txt
+++ b/doc/build-sdk-meson.txt
@@ -85,6 +85,8 @@ Project-specific options are passed used -Doption=value::
meson -Dmax_lcores=8 smallbuild # scale build for smaller systems
+ meson -Denable_docs=true fullbuild # build and install docs
+
Examples of setting the same options using meson configure::
meson configure -Dwerror=true
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000000..afca2e7133
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+subdir('api')
diff --git a/meson.build b/meson.build
index 9999e8640a..09506ec48c 100644
--- a/meson.build
+++ b/meson.build
@@ -34,6 +34,9 @@ subdir('usertools')
subdir('app')
subdir('test')
+# build docs
+subdir('doc')
+
# build any examples explicitly requested - useful for developers
if get_option('examples') != ''
subdir('examples')
diff --git a/meson_options.txt b/meson_options.txt
index f20887212a..d38ba56e29 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -2,6 +2,8 @@ option('allow_invalid_socket_id', type: 'boolean', value: false,
description: 'allow out-of-range NUMA socket id\'s for platforms that don\'t report the value correctly')
option('enable_kmods', type: 'boolean', value: true,
description: 'build kernel modules')
+option('enable_docs', type: 'boolean', value: false,
+ description: 'build documentation')
option('examples', type: 'string', value: '',
description: 'Comma-separated list of examples to build by default')
option('include_subdir_arch', type: 'string', value: '',
--
2.18.0
next prev parent reply other threads:[~2018-09-10 20:10 UTC|newest]
Thread overview: 39+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-08-31 18:20 [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
2018-08-31 18:20 ` [PATCH 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-03 0:54 ` Thomas Monjalon
2018-09-03 9:07 ` Luca Boccassi
2018-09-07 16:13 ` Bruce Richardson
2018-09-07 16:56 ` Luca Boccassi
2018-08-31 18:20 ` [PATCH 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-03 1:03 ` Thomas Monjalon
2018-09-03 9:08 ` Luca Boccassi
2018-08-31 18:20 ` [PATCH 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-03 1:04 ` Thomas Monjalon
2018-08-31 18:20 ` [PATCH 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-03 1:09 ` Thomas Monjalon
2018-09-03 9:34 ` Luca Boccassi
2018-09-07 16:31 ` Bruce Richardson
2018-09-07 16:56 ` Luca Boccassi
2018-09-07 16:55 ` [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-07 16:55 ` [PATCH v2 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-07 16:55 ` [PATCH v2 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-07 16:55 ` [PATCH v2 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-10 15:47 ` Bruce Richardson
2018-09-10 16:15 ` Luca Boccassi
2018-09-10 15:49 ` [PATCH v2 1/4] mk: use script to generate examples.dox Bruce Richardson
2018-09-10 16:13 ` [PATCH v3 " Luca Boccassi
2018-09-10 16:13 ` [PATCH v3 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-10 16:13 ` [PATCH v3 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-10 16:13 ` [PATCH v3 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-10 17:30 ` Bruce Richardson
2018-09-10 17:32 ` Bruce Richardson
2018-09-10 17:35 ` Luca Boccassi
2018-09-10 20:09 ` [PATCH v4 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-10 20:09 ` [PATCH v4 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-10 20:09 ` [PATCH v4 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-10 20:10 ` Luca Boccassi [this message]
2018-09-11 20:42 ` [PATCH v5 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-11 20:42 ` [PATCH v5 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-11 20:42 ` [PATCH v5 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-11 20:42 ` [PATCH v5 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-18 13:48 ` Thomas Monjalon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20180910201000.11243-4-bluca@debian.org \
--to=bluca@debian.org \
--cc=bruce.richardson@intel.com \
--cc=dev@dpdk.org \
--cc=john.mcnamara@intel.com \
--cc=marko.kovacevic@intel.com \
--cc=thomas@monjalon.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.