[v3,4/4] build: generate API documentation with Meson
Checks
Commit Message
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
Comments
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.
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.
On Mon, 2018-09-10 at 18:30 +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.
Yeah that makes sense, I can rework that once the sphinx stuff is also
in.
Did you manage to get it working yet?
new file mode 100755
@@ -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
new file mode 100644
@@ -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
@@ -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
new file mode 100644
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+subdir('api')
@@ -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')
@@ -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: '',