From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id EFF654C91 for ; Mon, 10 Sep 2018 19:31:08 +0200 (CEST) X-Amp-Result: UNKNOWN X-Amp-Original-Verdict: FILE UNKNOWN X-Amp-File-Uploaded: False Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 10 Sep 2018 10:31:07 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,356,1531810800"; d="scan'208";a="88781784" Received: from bricha3-mobl.ger.corp.intel.com ([10.252.2.6]) by fmsmga001.fm.intel.com with SMTP; 10 Sep 2018 10:30:52 -0700 Received: by (sSMTP sendmail emulation); Mon, 10 Sep 2018 18:30:52 +0100 Date: Mon, 10 Sep 2018 18:30:51 +0100 From: Bruce Richardson To: Luca Boccassi Cc: dev@dpdk.org, john.mcnamara@intel.com, marko.kovacevic@intel.com, thomas@monjalon.net Message-ID: <20180910173051.GA26200@bricha3-MOBL.ger.corp.intel.com> References: <20180907165524.23982-1-bluca@debian.org> <20180910161306.12568-1-bluca@debian.org> <20180910161306.12568-4-bluca@debian.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20180910161306.12568-4-bluca@debian.org> Organization: Intel Research and Development Ireland Ltd. User-Agent: Mutt/1.10.1 (2018-07-13) Subject: Re: [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 10 Sep 2018 17:31:09 -0000 On Mon, Sep 10, 2018 at 05:13:06PM +0100, Luca Boccassi wrote: > Signed-off-by: Luca Boccassi > --- > 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 > + > +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 > + > +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.