| Message ID | 20180831182055.30772-5-bluca@debian.org (mailing list archive) |
|---|---|
| State | Superseded, archived |
| Delegated to: | Thomas Monjalon |
| Headers | show |
| Series | Meson: build Doxygen documentation | expand |
| Context | Check | Description |
|---|---|---|
| ci/checkpatch | success | coding style OK |
| ci/Intel-compilation | success | Compilation OK |
31/08/2018 20:20, Luca Boccassi: > Both a configuration-time "enable_docs" boolean option and an optional > 'ninja doc' target are available. Note that due to a Meson bug for now > the latter will only build, but not install the files. > > Signed-off-by: Luca Boccassi <bluca@debian.org> > --- > doc/api/generate_doxygen.sh | 10 ++++++++ > doc/api/meson.build | 51 +++++++++++++++++++++++++++++++++++++ > doc/build-sdk-meson.txt | 2 ++ > doc/meson.build | 4 +++ > meson.build | 3 +++ > meson_options.txt | 2 ++ > 6 files changed, 72 insertions(+) You use generate_doxygen.sh only with meson? Shouldn't we use the same in mk/rte.sdkdoc.mk?
On Mon, 2018-09-03 at 03:09 +0200, Thomas Monjalon wrote: > 31/08/2018 20:20, Luca Boccassi: > > Both a configuration-time "enable_docs" boolean option and an > > optional > > 'ninja doc' target are available. Note that due to a Meson bug for > > now > > the latter will only build, but not install the files. > > > > Signed-off-by: Luca Boccassi <bluca@debian.org> > > --- > > doc/api/generate_doxygen.sh | 10 ++++++++ > > doc/api/meson.build | 51 > > +++++++++++++++++++++++++++++++++++++ > > doc/build-sdk-meson.txt | 2 ++ > > doc/meson.build | 4 +++ > > meson.build | 3 +++ > > meson_options.txt | 2 ++ > > 6 files changed, 72 insertions(+) > > You use generate_doxygen.sh only with meson? > Shouldn't we use the same in mk/rte.sdkdoc.mk? I was kinda hoping somebody would be able to suggest an alternative that avoids the need for generate_doxygen.sh - the issue being that with Meson's "custom_target" you can't specify a subdirectory in input/ouput (and the directory is generated at build time so can't have a meson.build in it), and also you cannot use the same "output" twice. So I can't see a way to have an additional custom_target to run the CSS generation, hence the script. Changing the makefile to use the script will make it a bit more complicated, as the doxygen file will need to be generated rather than passed by piping stout/in, so the rule will have to be split into 3: create directory -> create file -> call doxygen. Not sure it's worth it?
On Fri, Aug 31, 2018 at 07:20:55PM +0100, Luca Boccassi wrote: > Both a configuration-time "enable_docs" boolean option and an optional > 'ninja doc' target are available. Note that due to a Meson bug for now > the latter will only build, but not install the files. > > Signed-off-by: Luca Boccassi <bluca@debian.org> > --- > doc/api/generate_doxygen.sh | 10 ++++++++ > doc/api/meson.build | 51 +++++++++++++++++++++++++++++++++++++ > doc/build-sdk-meson.txt | 2 ++ > doc/meson.build | 4 +++ > meson.build | 3 +++ > meson_options.txt | 2 ++ > 6 files changed, 72 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..e44963e4a9 > --- /dev/null > +++ b/doc/api/meson.build > @@ -0,0 +1,51 @@ > +# SPDX-License-Identifier: BSD-3-Clause > +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org> > + > +# 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') > +doxygen = find_program('doxygen') This needs to be inside a conditional if we are not building docs. Otherwise overall build will error out if doxygen is missing - even if unused. /Bruce
On Fri, 2018-09-07 at 17:31 +0100, Bruce Richardson wrote: > On Fri, Aug 31, 2018 at 07:20:55PM +0100, Luca Boccassi wrote: > > Both a configuration-time "enable_docs" boolean option and an > > optional > > 'ninja doc' target are available. Note that due to a Meson bug for > > now > > the latter will only build, but not install the files. > > > > Signed-off-by: Luca Boccassi <bluca@debian.org> > > --- > > doc/api/generate_doxygen.sh | 10 ++++++++ > > doc/api/meson.build | 51 > > +++++++++++++++++++++++++++++++++++++ > > doc/build-sdk-meson.txt | 2 ++ > > doc/meson.build | 4 +++ > > meson.build | 3 +++ > > meson_options.txt | 2 ++ > > 6 files changed, 72 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..e44963e4a9 > > --- /dev/null > > +++ b/doc/api/meson.build > > @@ -0,0 +1,51 @@ > > +# SPDX-License-Identifier: BSD-3-Clause > > +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org> > > + > > +# 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') > > +doxygen = find_program('doxygen') > > This needs to be inside a conditional if we are not building docs. > Otherwise overall build will error out if doxygen is missing - even > if > unused. > > /Bruce Good point, forgot about that, done in v2
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..e44963e4a9 --- /dev/null +++ b/doc/api/meson.build @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org> + +# 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') +doxygen = find_program('doxygen') + +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) 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: '',
Both a configuration-time "enable_docs" boolean option and an optional 'ninja doc' target are available. Note that due to a Meson bug for now the latter will only build, but not install the files. Signed-off-by: Luca Boccassi <bluca@debian.org> --- doc/api/generate_doxygen.sh | 10 ++++++++ doc/api/meson.build | 51 +++++++++++++++++++++++++++++++++++++ doc/build-sdk-meson.txt | 2 ++ doc/meson.build | 4 +++ meson.build | 3 +++ meson_options.txt | 2 ++ 6 files changed, 72 insertions(+) create mode 100755 doc/api/generate_doxygen.sh create mode 100644 doc/api/meson.build create mode 100644 doc/meson.build