DPDK patches and discussions
 help / color / mirror / Atom feed
From: Bruce Richardson <bruce.richardson@intel.com>
To: Luca Boccassi <bluca@debian.org>
Cc: dev@dpdk.org, john.mcnamara@intel.com, marko.kovacevic@intel.com,
	thomas@monjalon.net
Subject: Re: [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson
Date: Mon, 10 Sep 2018 18:32:52 +0100
Message-ID: <20180910173252.GA3432@bricha3-MOBL.ger.corp.intel.com> (raw)
In-Reply-To: <20180910173051.GA26200@bricha3-MOBL.ger.corp.intel.com>

On Mon, Sep 10, 2018 at 06:30:51PM +0100, Bruce Richardson wrote:
> On Mon, Sep 10, 2018 at 05:13:06PM +0100, Luca Boccassi wrote:
> > Signed-off-by: Luca Boccassi <bluca@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@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
> 
> 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.

And the main reason I don't recommend changing this yet, is that until we
add in the extra doc builds we probably won't know what the result needs to
look like anyway, so little point in just guessing what the solution would
be.

  reply	other threads:[~2018-09-10 17:34 UTC|newest]

Thread overview: 39+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
2018-08-31 18:20 ` [dpdk-dev] [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 ` [dpdk-dev] [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 ` [dpdk-dev] [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 ` [dpdk-dev] [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 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-07 16:55   ` [dpdk-dev] [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   ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Bruce Richardson
2018-09-10 16:13   ` [dpdk-dev] [PATCH v3 " Luca Boccassi
2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-10 16:13     ` [dpdk-dev] [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 [this message]
2018-09-10 17:35         ` Luca Boccassi
2018-09-10 20:09 ` [dpdk-dev] [PATCH v4 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-10 20:10   ` [dpdk-dev] [PATCH v4 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-11 20:42 ` [dpdk-dev] [PATCH v5 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-11 20:42   ` [dpdk-dev] [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=20180910173252.GA3432@bricha3-MOBL.ger.corp.intel.com \
    --to=bruce.richardson@intel.com \
    --cc=bluca@debian.org \
    --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

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git