[dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson

[Bruce Richardson]

On Mon, Sep 10, 2018 at 05:13:06PM +0100, Luca Boccassi wrote:
> Signed-off-by: Luca Boccassi <bluca at debian.org>
> ---
> 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)
> 
>  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 at 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 at 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

While I suggest we keep this in this patchset for now, this isn't going to
scale as we add in more targets for building the PDF/HTML guides. I think
for that case, we may need to use an array variable for the "depends"
target, and add things to that as we process the documentation meson.build
files. That might work better for cases where we have some but not all doc
build capabilities, e.g. missing sphinx but not doxygen.