Meson: build Doxygen documentation
cover Meson: build Doxygen documentation
I have tested this by using diffoscope between the docs built by the makefiles and by this Meson patchset, and verified they are all identical.
There are both a new "doc" target (ninja doc) and a configuration option. This is due to the following bug in Meson:
https://github.com/mesonbuild/meson/issues/4107
because of it it's not possible to have simply an optional target, as its files will not be installed.
So by default the documentation is off, if one wants to just build it 'ninja doc' can be used, but if one wants to both build and install the config option 'enable_docs' has to be enabled.
A couple of small refactoring was done to the makefile doc build, to make things easier and doable by both build systems.
Luca Boccassi (4):
mk: use script to generate examples.dox
mk: use templated doxygen config, modified on the fly
build: use same version as make showversion in Meson
build: generate API documentation with Meson
doc/api/doxy-api.conf | 87 -------------------------------- doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++ doc/api/generate_doxygen.sh | 10 ++++ doc/api/generate_examples.sh | 14 ++++++ doc/api/meson.build | 51 +++++++++++++++++++ doc/build-sdk-meson.txt | 2 + doc/meson.build | 4 ++ meson.build | 5 +- meson_options.txt | 2 + mk/rte.sdkdoc.mk | 21 +++----- 10 files changed, 191 insertions(+), 101 deletions(-) delete mode 100644 doc/api/doxy-api.conf create mode 100644 doc/api/doxy-api.conf.in create mode 100755 doc/api/generate_doxygen.sh create mode 100755 doc/api/generate_examples.sh create mode 100644 doc/api/meson.build create mode 100644 doc/meson.build
Signature · 1 line
2.18.0
PATCH 1/4 mk: use script to generate examples.dox
This will make it possible to generate the file in the same way from Meson as well.
--- doc/api/generate_examples.sh | 14 ++++++++++++++ mk/rte.sdkdoc.mk | 5 +---- 2 files changed, 15 insertions(+), 4 deletions(-) create mode 100755 doc/api/generate_examples.sh
doc/api/generate_examples.sh new file +14 -0
@@ -0,0 +1,14 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +EXAMPLES_DIR=$1 +API_EXAMPLES=$2 + +# SC2129 - avoid multiple individual redirects +{ \ + printf '/**\n'; \ + printf '@page examples DPDK Example Programs\n\n'; \ + find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort; \ + printf '*/\n'; \ +} > "${API_EXAMPLES}"
mk/rte.sdkdoc.mk +1 -4
@@ -63,10 +63,7 @@ api-html-clean: $(API_EXAMPLES): api-html-clean $(Q)mkdir -p $(@D) - @printf '/**\n' > $(API_EXAMPLES) - @printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES) - @find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES) - @printf '*/\n' >> $(API_EXAMPLES) + $(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES) guides-pdf-clean: guides-pdf-img-clean guides-pdf-img-clean:
Signature · 1 line
2.18.0
Re: [PATCH 1/4] mk: use script to generate examples.dox
31/08/2018 20:20, Luca Boccassi:
Quoted 1 line
+# SC2129 - avoid multiple individual redirects
What is SC2129 ?
doc/api/generate_examples.sh line 14
Quoted 6 lines
doc/api/generate_examples.sh new file +6
-0+{ \ + printf '/**\n'; \ + printf '@page examples DPDK Example Programs\n\n'; \ + find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort; \ + printf '*/\n'; \ +} > "${API_EXAMPLES}"
Why using backslashes (continuation lines)?
Re: [PATCH 1/4] mk: use script to generate examples.dox
Quoted 4 lines · Thomas Monjalon
31/08/2018 20:20, Luca Boccassi:
Quoted 1 line
+# SC2129 - avoid multiple individual redirects
What is SC2129 ?
shellcheck - will clarify in v2
Quoted 9 lines
Quoted 7 lines
+{ \
+ printf '/**\n'; \
+ printf '@page examples DPDK Example Programs\n\n'; \
+ find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort; \
+ printf '*/\n'; \
+} > "${API_EXAMPLES}"Why using backslashes (continuation lines)?
Good point, will remove in v2
Signature · 2 lines
Kind regards, Luca Boccassi
Re: [PATCH 1/4] mk: use script to generate examples.dox
Quoted 18 lines · Luca Boccassi
Quoted 4 lines · Thomas Monjalon
31/08/2018 20:20, Luca Boccassi:
Quoted 1 line
+# SC2129 - avoid multiple individual redirects
What is SC2129 ?
shellcheck - will clarify in v2
Quoted 9 lines
Quoted 7 lines
+{ \
+ printf '/**\n'; \
+ printf '@page examples DPDK Example Programs\n\n'; \
+ find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort; \
+ printf '*/\n'; \
+} > "${API_EXAMPLES}"Why using backslashes (continuation lines)?
Quoted 2 lines
Good point, will remove in v2
Agree, rather than using continuation lines, I suggest one of the following:
* use exec > ${API_EXAMPLES} at the top of the script
* let the script just print to stdout and have make/meson put that in the output file for you.
/Bruce
Re: [PATCH 1/4] mk: use script to generate examples.dox
Quoted 23 lines · Bruce Richardson
Quoted 19 lines · Luca Boccassi
Quoted 4 lines · Thomas Monjalon
31/08/2018 20:20, Luca Boccassi:
Quoted 1 line
+# SC2129 - avoid multiple individual redirects
What is SC2129 ?
shellcheck - will clarify in v2
Quoted 10 lines
Quoted 8 lines
+{ \
+ printf '/**\n'; \
+ printf '@page examples DPDK Example Programs\n\n'; \
+ find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@examp le
examples/%P\n' | LC_ALL=C sort; \
+ printf '*/\n'; \
+} > "${API_EXAMPLES}"Why using backslashes (continuation lines)?
Quoted 2 lines
Good point, will remove in v2
Quoted 8 lines
Agree, rather than using continuation lines, I suggest one of the following:
* use exec > ${API_EXAMPLES} at the top of the script
* let the script just print to stdout and have make/meson put that in the
output file for you./Bruce
exec > works and checkbashism is also happy with it, so used that in v2
Signature · 2 lines
Kind regards, Luca Boccassi
PATCH 2/4 mk: use templated doxygen config, modified on the fly
In reply to Luca BoccassiThis will allow the same config file to be used from Meson. The result has been verified to be identical via diffoscope.
--- doc/api/doxy-api.conf | 87 ------------------------------------ doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++ mk/rte.sdkdoc.mk | 16 +++---- 3 files changed, 103 insertions(+), 96 deletions(-) delete mode 100644 doc/api/doxy-api.conf create mode 100644 doc/api/doxy-api.conf.in
doc/api/doxy-api.conf deleted +0 -87
@@ -1,87 +0,0 @@ -# SPDX-License-Identifier: BSD-3-Clause -# Copyright 2013-2017 6WIND S.A. - -PROJECT_NAME = DPDK -INPUT = doc/api/doxy-api-index.md \ - drivers/crypto/scheduler \ - drivers/mempool/dpaa2 \ - drivers/net/bnxt \ - drivers/net/bonding \ - drivers/net/dpaa \ - drivers/net/i40e \ - drivers/net/ixgbe \ - drivers/net/softnic \ - drivers/raw/dpaa2_cmdif \ - drivers/raw/dpaa2_qdma \ - lib/librte_eal/common/include \ - lib/librte_eal/common/include/generic \ - lib/librte_acl \ - lib/librte_bbdev \ - lib/librte_bitratestats \ - lib/librte_bpf \ - lib/librte_cfgfile \ - lib/librte_cmdline \ - lib/librte_compat \ - lib/librte_compressdev \ - lib/librte_cryptodev \ - lib/librte_distributor \ - lib/librte_efd \ - lib/librte_ethdev \ - lib/librte_eventdev \ - lib/librte_flow_classify \ - lib/librte_gro \ - lib/librte_gso \ - lib/librte_hash \ - lib/librte_ip_frag \ - lib/librte_jobstats \ - lib/librte_kni \ - lib/librte_kvargs \ - lib/librte_latencystats \ - lib/librte_lpm \ - lib/librte_mbuf \ - lib/librte_member \ - lib/librte_mempool \ - lib/librte_meter \ - lib/librte_metrics \ - lib/librte_net \ - lib/librte_pci \ - lib/librte_pdump \ - lib/librte_pipeline \ - lib/librte_port \ - lib/librte_power \ - lib/librte_rawdev \ - lib/librte_reorder \ - lib/librte_ring \ - lib/librte_sched \ - lib/librte_security \ - lib/librte_table \ - lib/librte_timer \ - lib/librte_vhost -FILE_PATTERNS = rte_*.h \ - cmdline.h -PREDEFINED = __DOXYGEN__ \ - VFIO_PRESENT \ - __attribute__(x)= - -OPTIMIZE_OUTPUT_FOR_C = YES -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -EXTRACT_STATIC = YES -DISTRIBUTE_GROUP_DOC = YES -HIDE_UNDOC_MEMBERS = YES -HIDE_UNDOC_CLASSES = YES -HIDE_SCOPE_NAMES = YES -GENERATE_DEPRECATEDLIST = NO -VERBATIM_HEADERS = NO -ALPHABETICAL_INDEX = NO - -HTML_TIMESTAMP = NO -HTML_DYNAMIC_SECTIONS = YES -SEARCHENGINE = NO -SORT_MEMBER_DOCS = NO -SOURCE_BROWSER = YES - -EXAMPLE_PATH = examples -EXAMPLE_PATTERNS = *.c -EXAMPLE_RECURSIVE = YES
doc/api/doxy-api.conf.in new file +96 -0
96 lines not on this page · raw message
mk/rte.sdkdoc.mk +7 -9
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean api-html: $(API_EXAMPLES) @echo 'doxygen for API...' $(Q)mkdir -p $(RTE_OUTPUT)/doc/html - $(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf && \ - printf 'PROJECT_NUMBER = ' && \ - $(MAKE) -rRs showversion && \ - echo INPUT += $(API_EXAMPLES) && \ - echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \ - echo HTML_OUTPUT = html/api && \ - echo GENERATE_HTML = YES && \ - echo GENERATE_LATEX = NO && \ - echo GENERATE_MAN = NO )| \ + $(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \ + -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|" \ + -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|" \ + -e "s|@HTML_OUTPUT@|html/api|" \ + -e "s|@TOPDIR@|./|g" \ + -e "s|@STRIP_FROM_PATH@|./|g" \ + $(RTE_SDK)/doc/api/doxy-api.conf.in)| \ doxygen - $(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
Signature · 1 line
2.18.0
Re: [PATCH 2/4] mk: use templated doxygen config, modified on the fly
Good idea.
While at putting all in the same file (template),
we can re-organize the template a bit.
31/08/2018 20:20, Luca Boccassi:
Quoted 82 lines
doc/api/doxy-api.conf.in new file +79
-0@@ -0,0 +1,96 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2013-2017 6WIND S.A. + +PROJECT_NAME = DPDK +INPUT = @TOPDIR@/doc/api/doxy-api-index.md \ + @TOPDIR@/drivers/crypto/scheduler \ + @TOPDIR@/drivers/mempool/dpaa2 \ + @TOPDIR@/drivers/net/bnxt \ + @TOPDIR@/drivers/net/bonding \ + @TOPDIR@/drivers/net/dpaa \ + @TOPDIR@/drivers/net/i40e \ + @TOPDIR@/drivers/net/ixgbe \ + @TOPDIR@/drivers/net/softnic \ + @TOPDIR@/drivers/raw/dpaa2_cmdif \ + @TOPDIR@/drivers/raw/dpaa2_qdma \ + @TOPDIR@/lib/librte_eal/common/include \ + @TOPDIR@/lib/librte_eal/common/include/generic \ + @TOPDIR@/lib/librte_acl \ + @TOPDIR@/lib/librte_bbdev \ + @TOPDIR@/lib/librte_bitratestats \ + @TOPDIR@/lib/librte_bpf \ + @TOPDIR@/lib/librte_cfgfile \ + @TOPDIR@/lib/librte_cmdline \ + @TOPDIR@/lib/librte_compat \ + @TOPDIR@/lib/librte_compressdev \ + @TOPDIR@/lib/librte_cryptodev \ + @TOPDIR@/lib/librte_distributor \ + @TOPDIR@/lib/librte_efd \ + @TOPDIR@/lib/librte_ethdev \ + @TOPDIR@/lib/librte_eventdev \ + @TOPDIR@/lib/librte_flow_classify \ + @TOPDIR@/lib/librte_gro \ + @TOPDIR@/lib/librte_gso \ + @TOPDIR@/lib/librte_hash \ + @TOPDIR@/lib/librte_ip_frag \ + @TOPDIR@/lib/librte_jobstats \ + @TOPDIR@/lib/librte_kni \ + @TOPDIR@/lib/librte_kvargs \ + @TOPDIR@/lib/librte_latencystats \ + @TOPDIR@/lib/librte_lpm \ + @TOPDIR@/lib/librte_mbuf \ + @TOPDIR@/lib/librte_member \ + @TOPDIR@/lib/librte_mempool \ + @TOPDIR@/lib/librte_meter \ + @TOPDIR@/lib/librte_metrics \ + @TOPDIR@/lib/librte_net \ + @TOPDIR@/lib/librte_pci \ + @TOPDIR@/lib/librte_pdump \ + @TOPDIR@/lib/librte_pipeline \ + @TOPDIR@/lib/librte_port \ + @TOPDIR@/lib/librte_power \ + @TOPDIR@/lib/librte_rawdev \ + @TOPDIR@/lib/librte_reorder \ + @TOPDIR@/lib/librte_ring \ + @TOPDIR@/lib/librte_sched \ + @TOPDIR@/lib/librte_security \ + @TOPDIR@/lib/librte_table \ + @TOPDIR@/lib/librte_timer \ + @TOPDIR@/lib/librte_vhost +FILE_PATTERNS = rte_*.h \ + cmdline.h +PREDEFINED = __DOXYGEN__ \ + VFIO_PRESENT \ + __attribute__(x)= + +OPTIMIZE_OUTPUT_FOR_C = YES +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +EXTRACT_STATIC = YES +DISTRIBUTE_GROUP_DOC = YES +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_SCOPE_NAMES = YES +GENERATE_DEPRECATEDLIST = NO +VERBATIM_HEADERS = NO +ALPHABETICAL_INDEX = NO + +HTML_TIMESTAMP = NO
doc/api/doxy-api.conf.in line 89
Quoted 10 lines
doc/api/doxy-api.conf.in new file +10
-0+HTML_DYNAMIC_SECTIONS = YES +SEARCHENGINE = NO +SORT_MEMBER_DOCS = NO +SOURCE_BROWSER = YES + +EXAMPLE_PATH = @TOPDIR@/examples +EXAMPLE_PATTERNS = *.c +EXAMPLE_RECURSIVE = YES + +PROJECT_NUMBER = @VERSION@
could be below PROJECT_NAME
doc/api/doxy-api.conf.in line 90
Quoted 1 line
doc/api/doxy-api.conf.in new file +1
-0+INPUT += @API_EXAMPLES@
can be at the end of INPUT list
doc/api/doxy-api.conf.in line 92
Quoted 2 lines
doc/api/doxy-api.conf.in new file +2
-0+OUTPUT_DIRECTORY = @OUTPUT@ +HTML_OUTPUT = @HTML_OUTPUT@
can be below GENERATE_HTML
Quoted 4 lines
doc/api/doxy-api.conf.in new file +4
-0+STRIP_FROM_PATH = @STRIP_FROM_PATH@ +GENERATE_HTML = YES +GENERATE_LATEX = NO +GENERATE_MAN = NO
Re: [PATCH 2/4] mk: use templated doxygen config, modified on the fly
Quoted 110 lines · Thomas Monjalon
Good idea.
While at putting all in the same file (template),
we can re-organize the template a bit.31/08/2018 20:20, Luca Boccassi:
Quoted 83 lines
doc/api/doxy-api.conf.in new file +17
-0@@ -0,0 +1,96 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2013-2017 6WIND S.A. + +PROJECT_NAME = DPDK +INPUT = @TOPDIR@/doc/api/doxy-api-index.md \ + @TOPDIR@/drivers/crypto/scheduler \ + @TOPDIR@/drivers/mempool/dpaa2 \ + @TOPDIR@/drivers/net/bnxt \ + @TOPDIR@/drivers/net/bonding \ + @TOPDIR@/drivers/net/dpaa \ + @TOPDIR@/drivers/net/i40e \ + @TOPDIR@/drivers/net/ixgbe \ + @TOPDIR@/drivers/net/softnic \ + @TOPDIR@/drivers/raw/dpaa2_cmdif \ + @TOPDIR@/drivers/raw/dpaa2_qdma \ + @TOPDIR@/lib/librte_eal/common/include \ + @TOPDIR@/lib/librte_eal/common/include/generic \
+ @TOPDIR@/lib/librte_acl \
+ @TOPDIR@/lib/librte_bbdev \
+ @TOPDIR@/lib/librte_bitratestats \
+ @TOPDIR@/lib/librte_bpf \
+ @TOPDIR@/lib/librte_cfgfile \
+ @TOPDIR@/lib/librte_cmdline \
+ @TOPDIR@/lib/librte_compat \
+ @TOPDIR@/lib/librte_compressdev \
+ @TOPDIR@/lib/librte_cryptodev \
+ @TOPDIR@/lib/librte_distributor \
+ @TOPDIR@/lib/librte_efd \
+ @TOPDIR@/lib/librte_ethdev \
+ @TOPDIR@/lib/librte_eventdev \
+ @TOPDIR@/lib/librte_flow_classify \
+ @TOPDIR@/lib/librte_gro \
+ @TOPDIR@/lib/librte_gso \
+ @TOPDIR@/lib/librte_hash \
+ @TOPDIR@/lib/librte_ip_frag \
+ @TOPDIR@/lib/librte_jobstats \
+ @TOPDIR@/lib/librte_kni \
+ @TOPDIR@/lib/librte_kvargs \
+ @TOPDIR@/lib/librte_latencystats \
+ @TOPDIR@/lib/librte_lpm \
+ @TOPDIR@/lib/librte_mbuf \
+ @TOPDIR@/lib/librte_member \
+ @TOPDIR@/lib/librte_mempool \
+ @TOPDIR@/lib/librte_meter \
+ @TOPDIR@/lib/librte_metrics \
+ @TOPDIR@/lib/librte_net \
+ @TOPDIR@/lib/librte_pci \
+ @TOPDIR@/lib/librte_pdump \
+ @TOPDIR@/lib/librte_pipeline \
+ @TOPDIR@/lib/librte_port \
+ @TOPDIR@/lib/librte_power \
+ @TOPDIR@/lib/librte_rawdev \
+ @TOPDIR@/lib/librte_reorder \
+ @TOPDIR@/lib/librte_ring \
+ @TOPDIR@/lib/librte_sched \
+ @TOPDIR@/lib/librte_security \
+ @TOPDIR@/lib/librte_table \
+ @TOPDIR@/lib/librte_timer \
+ @TOPDIR@/lib/librte_vhostdoc/api/doxy-api.conf.in new file +20
-0+FILE_PATTERNS = rte_*.h \ + cmdline.h +PREDEFINED = __DOXYGEN__ \ + VFIO_PRESENT \ + __attribute__(x)= + +OPTIMIZE_OUTPUT_FOR_C = YES +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +EXTRACT_STATIC = YES +DISTRIBUTE_GROUP_DOC = YES +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_SCOPE_NAMES = YES +GENERATE_DEPRECATEDLIST = NO +VERBATIM_HEADERS = NO +ALPHABETICAL_INDEX = NO + +HTML_TIMESTAMP = NOdoc/api/doxy-api.conf.in line 89
Quoted 10 lines
doc/api/doxy-api.conf.in new file +10
-0+HTML_DYNAMIC_SECTIONS = YES +SEARCHENGINE = NO +SORT_MEMBER_DOCS = NO +SOURCE_BROWSER = YES + +EXAMPLE_PATH = @TOPDIR@/examples +EXAMPLE_PATTERNS = *.c +EXAMPLE_RECURSIVE = YES + +PROJECT_NUMBER = @VERSION@could be below
PROJECT_NAMEQuoted 1 line
+INPUT += @API_EXAMPLES@
can be at the end of INPUT list
doc/api/doxy-api.conf.in line 92
Quoted 2 lines
doc/api/doxy-api.conf.in new file +2
-0+OUTPUT_DIRECTORY = @OUTPUT@ +HTML_OUTPUT = @HTML_OUTPUT@can be below
GENERATE_HTML
Quoted 4 lines
doc/api/doxy-api.conf.in line 96
Quoted 4 lines
doc/api/doxy-api.conf.in new file +4
-0+STRIP_FROM_PATH = @STRIP_FROM_PATH@ +GENERATE_HTML = YES +GENERATE_LATEX = NO +GENERATE_MAN = NO
Ok, will do in v2
Signature · 2 lines
Kind regards, Luca Boccassi
PATCH 3/4 build: use same version as make showversion in Meson
In reply to Luca Boccassimake showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0, causing among other things a difference in the generated documentation.
--- meson.build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
@@ -2,7 +2,7 @@ # Copyright(c) 2017 Intel Corporation project('DPDK', 'C', - version: '18.11-rc0', + version: '18.11.0-rc0', license: 'BSD', default_options: ['buildtype=release', 'default_library=static'], meson_version: '>= 0.41'
Signature · 1 line
2.18.0
Re: [PATCH 3/4] build: use same version as make showversion in Meson
31/08/2018 20:20, Luca Boccassi:
Quoted 6 lines
make showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0, causing among other things a difference in the generated documentation.
Fixes 76b9d9de5c7d ("version: 18.11-rc0")Signed-off-by Luca Boccassi <[email protected]>
PATCH 4/4 build: generate API documentation with Meson
In reply to Luca BoccassiBoth 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.
--- 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
doc/api/generate_doxygen.sh new file +10 -0
@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
doc/api/meson.build new file +51 -0
51 lines not on this page · raw message
doc/build-sdk-meson.txt +2 -0
@@ -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
doc/meson.build new file +4 -0
@@ -0,0 +1,4 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +subdir('api')
meson.build +3 -0
@@ -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')
meson_options.txt +2 -0
@@ -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: '',
Signature · 1 line
2.18.0
Re: [PATCH 4/4] build: generate API documentation with Meson
31/08/2018 20:20, Luca Boccassi:
Quoted 5 lines
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 <[email protected]>
Quoted 8 lines
--- 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?
Re: [PATCH 4/4] build: generate API documentation with Meson
Quoted 18 lines · Thomas Monjalon
31/08/2018 20:20, Luca Boccassi:
Quoted 15 lines
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 <[email protected]>---
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 ++Quoted 1 line
6 files changed, 72 insertions(+)
Quoted 2 lines
You use
generate_doxygen.shonly with meson?
Shouldn't we use the same inmk/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?
Signature · 2 lines
Kind regards, Luca Boccassi
Re: [PATCH 4/4] build: generate API documentation with Meson
In reply to Luca BoccassiQuoted 40 lines · 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 <[email protected]>--- 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.builddoc/api/generate_doxygen.sh new file +10
-0@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.cssdoc/api/meson.build new file +1
-0@@ -0,0 +1,51 @@ +# SPDX-License-Identifier: BSD-3-Clause
doc/api/meson.build line 11
Quoted 10 lines
doc/api/meson.build new file +10
-0+# Copyright(c) 2018 Luca Boccassi <[email protected]> + +# 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
Re: [PATCH 4/4] build: generate API documentation with Meson
Quoted 64 lines · Bruce Richardson
Quoted 52 lines · 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 <[email protected]>---
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.builddoc/api/generate_doxygen.sh new file +10
-0@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.cssdoc/api/meson.build new file +4
-0@@ -0,0 +1,51 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +# due to the CSS customisation script, which needs to run on afile that
+# is in a subdirectory that is created at build time and thus it cannot
+# be an individualcustom_target, we need to wrap the doxygen call in adoc/api/meson.build line 11
Quoted 5 lines
doc/api/meson.build new file +5
-0+# 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.
Quoted 1 line
/Bruce
Good point, forgot about that, done in v2
Signature · 2 lines
Kind regards, Luca Boccassi
PATCH v2 1/4 mk: use script to generate examples.dox
In reply to Luca BoccassiThis will make it possible to generate the file in the same way from Meson as well.
---
v2: simplified script by using exec > file
doc/api/generate_examples.sh | 12 ++++++++++++ mk/rte.sdkdoc.mk | 5 +---- 2 files changed, 13 insertions(+), 4 deletions(-) create mode 100755 doc/api/generate_examples.sh
doc/api/generate_examples.sh new file +12 -0
@@ -0,0 +1,12 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +EXAMPLES_DIR=$1 +API_EXAMPLES=$2 + +exec > "${API_EXAMPLES}" +printf '/**\n' +printf '@page examples DPDK Example Programs\n\n' +find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort +printf '*/\n'
mk/rte.sdkdoc.mk +1 -4
@@ -63,10 +63,7 @@ api-html-clean: $(API_EXAMPLES): api-html-clean $(Q)mkdir -p $(@D) - @printf '/**\n' > $(API_EXAMPLES) - @printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES) - @find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES) - @printf '*/\n' >> $(API_EXAMPLES) + $(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES) guides-pdf-clean: guides-pdf-img-clean guides-pdf-img-clean:
Signature · 1 line
2.18.0
PATCH v2 2/4 mk: use templated doxygen config, modified on the fly
This will allow the same config file to be used from Meson. The result has been verified to be identical via diffoscope.
---
v2: reordered generated fields as requested
doc/api/doxy-api.conf | 87 ------------------------------------ doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++ mk/rte.sdkdoc.mk | 16 +++---- 3 files changed, 103 insertions(+), 96 deletions(-) delete mode 100644 doc/api/doxy-api.conf create mode 100644 doc/api/doxy-api.conf.in
doc/api/doxy-api.conf deleted +0 -87
@@ -1,87 +0,0 @@ -# SPDX-License-Identifier: BSD-3-Clause -# Copyright 2013-2017 6WIND S.A. - -PROJECT_NAME = DPDK -INPUT = doc/api/doxy-api-index.md \ - drivers/crypto/scheduler \ - drivers/mempool/dpaa2 \ - drivers/net/bnxt \ - drivers/net/bonding \ - drivers/net/dpaa \ - drivers/net/i40e \ - drivers/net/ixgbe \ - drivers/net/softnic \ - drivers/raw/dpaa2_cmdif \ - drivers/raw/dpaa2_qdma \ - lib/librte_eal/common/include \ - lib/librte_eal/common/include/generic \ - lib/librte_acl \ - lib/librte_bbdev \ - lib/librte_bitratestats \ - lib/librte_bpf \ - lib/librte_cfgfile \ - lib/librte_cmdline \ - lib/librte_compat \ - lib/librte_compressdev \ - lib/librte_cryptodev \ - lib/librte_distributor \ - lib/librte_efd \ - lib/librte_ethdev \ - lib/librte_eventdev \ - lib/librte_flow_classify \ - lib/librte_gro \ - lib/librte_gso \ - lib/librte_hash \ - lib/librte_ip_frag \ - lib/librte_jobstats \ - lib/librte_kni \ - lib/librte_kvargs \ - lib/librte_latencystats \ - lib/librte_lpm \ - lib/librte_mbuf \ - lib/librte_member \ - lib/librte_mempool \ - lib/librte_meter \ - lib/librte_metrics \ - lib/librte_net \ - lib/librte_pci \ - lib/librte_pdump \ - lib/librte_pipeline \ - lib/librte_port \ - lib/librte_power \ - lib/librte_rawdev \ - lib/librte_reorder \ - lib/librte_ring \ - lib/librte_sched \ - lib/librte_security \ - lib/librte_table \ - lib/librte_timer \ - lib/librte_vhost -FILE_PATTERNS = rte_*.h \ - cmdline.h -PREDEFINED = __DOXYGEN__ \ - VFIO_PRESENT \ - __attribute__(x)= - -OPTIMIZE_OUTPUT_FOR_C = YES -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -EXTRACT_STATIC = YES -DISTRIBUTE_GROUP_DOC = YES -HIDE_UNDOC_MEMBERS = YES -HIDE_UNDOC_CLASSES = YES -HIDE_SCOPE_NAMES = YES -GENERATE_DEPRECATEDLIST = NO -VERBATIM_HEADERS = NO -ALPHABETICAL_INDEX = NO - -HTML_TIMESTAMP = NO -HTML_DYNAMIC_SECTIONS = YES -SEARCHENGINE = NO -SORT_MEMBER_DOCS = NO -SOURCE_BROWSER = YES - -EXAMPLE_PATH = examples -EXAMPLE_PATTERNS = *.c -EXAMPLE_RECURSIVE = YES
doc/api/doxy-api.conf.in new file +96 -0
96 lines not on this page · raw message
mk/rte.sdkdoc.mk +7 -9
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean api-html: $(API_EXAMPLES) @echo 'doxygen for API...' $(Q)mkdir -p $(RTE_OUTPUT)/doc/html - $(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf && \ - printf 'PROJECT_NUMBER = ' && \ - $(MAKE) -rRs showversion && \ - echo INPUT += $(API_EXAMPLES) && \ - echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \ - echo HTML_OUTPUT = html/api && \ - echo GENERATE_HTML = YES && \ - echo GENERATE_LATEX = NO && \ - echo GENERATE_MAN = NO )| \ + $(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \ + -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|" \ + -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|" \ + -e "s|@HTML_OUTPUT@|html/api|" \ + -e "s|@TOPDIR@|./|g" \ + -e "s|@STRIP_FROM_PATH@|./|g" \ + $(RTE_SDK)/doc/api/doxy-api.conf.in)| \ doxygen - $(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
Signature · 1 line
2.18.0
PATCH v2 3/4 build: use same version as make showversion in Meson
In reply to Luca Boccassimake showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0, causing among other things a difference in the generated documentation.
--- meson.build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
@@ -2,7 +2,7 @@ # Copyright(c) 2017 Intel Corporation project('DPDK', 'C', - version: '18.11-rc0', + version: '18.11.0-rc0', license: 'BSD', default_options: ['buildtype=release', 'default_library=static'], meson_version: '>= 0.41'
Signature · 1 line
2.18.0
PATCH v2 4/4 build: generate API documentation with Meson
In reply to Luca Boccassi---
v2: made doxygen dependency optional, skip doxygen build when not found
doc/api/generate_doxygen.sh | 10 +++++++ doc/api/meson.build | 54 +++++++++++++++++++++++++++++++++++++ doc/build-sdk-meson.txt | 2 ++ doc/meson.build | 4 +++ meson.build | 3 +++ meson_options.txt | 2 ++ 6 files changed, 75 insertions(+) create mode 100755 doc/api/generate_doxygen.sh create mode 100644 doc/api/meson.build create mode 100644 doc/meson.build
doc/api/generate_doxygen.sh new file +10 -0
@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
doc/api/meson.build new file +54 -0
54 lines not on this page · raw message
doc/build-sdk-meson.txt +2 -0
@@ -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
doc/meson.build new file +4 -0
@@ -0,0 +1,4 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +subdir('api')
meson.build +3 -0
@@ -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')
meson_options.txt +2 -0
@@ -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: '',
Signature · 1 line
2.18.0
Re: [PATCH v2 4/4] build: generate API documentation with Meson
Quoted 37 lines · Luca Boccassi
Signed-off-by Luca Boccassi <[email protected]>---
v2: made doxygen dependency optional, skip doxygen build when not founddoc/api/generate_doxygen.sh | 10 +++++++ doc/api/meson.build | 54 +++++++++++++++++++++++++++++++++++++ doc/build-sdk-meson.txt | 2 ++ doc/meson.build | 4 +++ meson.build | 3 +++ meson_options.txt | 2 ++ 6 files changed, 75 insertions(+) create mode 100755 doc/api/generate_doxygen.sh create mode 100644 doc/api/meson.build create mode 100644 doc/meson.builddoc/api/generate_doxygen.sh new file +10
-0@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.cssdoc/api/meson.build new file +0
-0
doc/api/meson.build line 4
Quoted 4 lines
doc/api/meson.build new file +4
-0@@ -0,0 +1,54 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +doxygen = find_program('doxygen', required: false)
Thinking about it, I think that "required" should be set to "get_option(enable_docs)", since if someone explicitly enables the docs they should be built and cause error if they can't be.
Quoted 40 lines
doc/api/meson.build new file +40
-0+ +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',
doc/api/meson.build line 54
Quoted 10 lines
doc/api/meson.build new file +10
-0+ 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) +endif
Suggestion: add a run_target in an else leg to just print out "no doxygen found" or similar message when ninja doc is called.
Re: [PATCH v2 4/4] build: generate API documentation with Meson
Quoted 42 lines · Bruce Richardson
Quoted 41 lines · Luca Boccassi
Signed-off-by Luca Boccassi <[email protected]>---
v2: made doxygen dependency optional, skip doxygen build when not founddoc/api/generate_doxygen.sh | 10 +++++++
doc/api/meson.build | 54
+++++++++++++++++++++++++++++++++++++
doc/build-sdk-meson.txt | 2 ++
doc/meson.build | 4 +++
meson.build | 3 +++
meson_options.txt | 2 ++6 files changed, 75 insertions(+)create mode 100755
doc/api/generate_doxygen.sh
create mode 100644 doc/api/meson.build
create mode 100644 doc/meson.builddoc/api/generate_doxygen.sh new file +10
-0@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.cssdoc/api/meson.build new file +1
-0@@ -0,0 +1,54 @@ +# SPDX-License-Identifier: BSD-3-Clause
Quoted 8 lines
doc/api/meson.build line 4
Quoted 3 lines
doc/api/meson.build new file +3
-0+# Copyright(c) 2018 Luca Boccassi <[email protected]> + +doxygen = find_program('doxygen', required: false)Thinking about it, I think that "required" should be set to "
get_option(enable_docs)", since if someone explicitly enables the docs
they should be built and cause error if they can't be.
Done in v3
Quoted 55 lines
Quoted 55 lines
doc/api/meson.build new file +3
-0+ +if doxygen.found() + # due to the CSS customisation script, which needs to runon a file that
doc/api/meson.build new file +1
-0+ # is in a subdirectory that is created at build time andthus it cannot
doc/api/meson.build new file +1
-0+ # be an individual custom_target, we need to wrap thedoxygen call in a
doc/api/meson.build new file +9
-0+ # 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
doc/api/meson.build new file +1
-0+ # if install is set to true it will override
build_by_defaultand it willdoc/api/meson.build new file +1
-0+ # cause the target to always be built. If install were tobe always set to
doc/api/meson.build new file +6
-0+ # 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@'],
doc/api/meson.build new file +7
-0+ 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'))
doc/api/meson.build new file +1
-0+ cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc','api'))
doc/api/meson.build new file +14
-0+ 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],doc/api/meson.build new file +1
-0+ install: get_option('enable_docs'),
Quoted 8 lines
doc/api/meson.build line 54
Quoted 5 lines
doc/api/meson.build new file +5
-0+ install_dir: htmldir, + build_by_default: false) + + run_target('doc', command: 'true', depends: doxy_build) +endifSuggestion: add a
run_targetin an else leg to just print out "no doxygen found" or similar message when ninja doc is called.
Done
Signature · 2 lines
Kind regards, Luca Boccassi
Re: [PATCH v2 1/4] mk: use script to generate examples.dox
In reply to Luca BoccassiQuoted 5 lines · Luca Boccassi
This will make it possible to generate the file in the same way from Meson as well.
Signed-off-by Luca Boccassi <[email protected]>---
Couple of comments on patch 4, otherwise looks ok to me.
PATCH v3 1/4 mk: use script to generate examples.dox
In reply to Luca BoccassiThis will make it possible to generate the file in the same way from Meson as well.
---
v2: simplified script by using exec > file
doc/api/generate_examples.sh | 12 ++++++++++++ mk/rte.sdkdoc.mk | 5 +---- 2 files changed, 13 insertions(+), 4 deletions(-) create mode 100755 doc/api/generate_examples.sh
doc/api/generate_examples.sh new file +12 -0
@@ -0,0 +1,12 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +EXAMPLES_DIR=$1 +API_EXAMPLES=$2 + +exec > "${API_EXAMPLES}" +printf '/**\n' +printf '@page examples DPDK Example Programs\n\n' +find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort +printf '*/\n'
mk/rte.sdkdoc.mk +1 -4
@@ -63,10 +63,7 @@ api-html-clean: $(API_EXAMPLES): api-html-clean $(Q)mkdir -p $(@D) - @printf '/**\n' > $(API_EXAMPLES) - @printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES) - @find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES) - @printf '*/\n' >> $(API_EXAMPLES) + $(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES) guides-pdf-clean: guides-pdf-img-clean guides-pdf-img-clean:
Signature · 1 line
2.18.0
PATCH v3 2/4 mk: use templated doxygen config, modified on the fly
This will allow the same config file to be used from Meson. The result has been verified to be identical via diffoscope.
---
v2: reordered generated fields as requested
doc/api/doxy-api.conf | 87 ------------------------------------ doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++ mk/rte.sdkdoc.mk | 16 +++---- 3 files changed, 103 insertions(+), 96 deletions(-) delete mode 100644 doc/api/doxy-api.conf create mode 100644 doc/api/doxy-api.conf.in
doc/api/doxy-api.conf deleted +0 -87
@@ -1,87 +0,0 @@ -# SPDX-License-Identifier: BSD-3-Clause -# Copyright 2013-2017 6WIND S.A. - -PROJECT_NAME = DPDK -INPUT = doc/api/doxy-api-index.md \ - drivers/crypto/scheduler \ - drivers/mempool/dpaa2 \ - drivers/net/bnxt \ - drivers/net/bonding \ - drivers/net/dpaa \ - drivers/net/i40e \ - drivers/net/ixgbe \ - drivers/net/softnic \ - drivers/raw/dpaa2_cmdif \ - drivers/raw/dpaa2_qdma \ - lib/librte_eal/common/include \ - lib/librte_eal/common/include/generic \ - lib/librte_acl \ - lib/librte_bbdev \ - lib/librte_bitratestats \ - lib/librte_bpf \ - lib/librte_cfgfile \ - lib/librte_cmdline \ - lib/librte_compat \ - lib/librte_compressdev \ - lib/librte_cryptodev \ - lib/librte_distributor \ - lib/librte_efd \ - lib/librte_ethdev \ - lib/librte_eventdev \ - lib/librte_flow_classify \ - lib/librte_gro \ - lib/librte_gso \ - lib/librte_hash \ - lib/librte_ip_frag \ - lib/librte_jobstats \ - lib/librte_kni \ - lib/librte_kvargs \ - lib/librte_latencystats \ - lib/librte_lpm \ - lib/librte_mbuf \ - lib/librte_member \ - lib/librte_mempool \ - lib/librte_meter \ - lib/librte_metrics \ - lib/librte_net \ - lib/librte_pci \ - lib/librte_pdump \ - lib/librte_pipeline \ - lib/librte_port \ - lib/librte_power \ - lib/librte_rawdev \ - lib/librte_reorder \ - lib/librte_ring \ - lib/librte_sched \ - lib/librte_security \ - lib/librte_table \ - lib/librte_timer \ - lib/librte_vhost -FILE_PATTERNS = rte_*.h \ - cmdline.h -PREDEFINED = __DOXYGEN__ \ - VFIO_PRESENT \ - __attribute__(x)= - -OPTIMIZE_OUTPUT_FOR_C = YES -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -EXTRACT_STATIC = YES -DISTRIBUTE_GROUP_DOC = YES -HIDE_UNDOC_MEMBERS = YES -HIDE_UNDOC_CLASSES = YES -HIDE_SCOPE_NAMES = YES -GENERATE_DEPRECATEDLIST = NO -VERBATIM_HEADERS = NO -ALPHABETICAL_INDEX = NO - -HTML_TIMESTAMP = NO -HTML_DYNAMIC_SECTIONS = YES -SEARCHENGINE = NO -SORT_MEMBER_DOCS = NO -SOURCE_BROWSER = YES - -EXAMPLE_PATH = examples -EXAMPLE_PATTERNS = *.c -EXAMPLE_RECURSIVE = YES
doc/api/doxy-api.conf.in new file +96 -0
96 lines not on this page · raw message
mk/rte.sdkdoc.mk +7 -9
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean api-html: $(API_EXAMPLES) @echo 'doxygen for API...' $(Q)mkdir -p $(RTE_OUTPUT)/doc/html - $(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf && \ - printf 'PROJECT_NUMBER = ' && \ - $(MAKE) -rRs showversion && \ - echo INPUT += $(API_EXAMPLES) && \ - echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \ - echo HTML_OUTPUT = html/api && \ - echo GENERATE_HTML = YES && \ - echo GENERATE_LATEX = NO && \ - echo GENERATE_MAN = NO )| \ + $(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \ + -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|" \ + -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|" \ + -e "s|@HTML_OUTPUT@|html/api|" \ + -e "s|@TOPDIR@|./|g" \ + -e "s|@STRIP_FROM_PATH@|./|g" \ + $(RTE_SDK)/doc/api/doxy-api.conf.in)| \ doxygen - $(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
Signature · 1 line
2.18.0
PATCH v3 3/4 build: use same version as make showversion in Meson
In reply to Luca Boccassimake showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0, causing among other things a difference in the generated documentation.
--- meson.build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
@@ -2,7 +2,7 @@ # Copyright(c) 2017 Intel Corporation project('DPDK', 'C', - version: '18.11-rc0', + version: '18.11.0-rc0', license: 'BSD', default_options: ['buildtype=release', 'default_library=static'], meson_version: '>= 0.41'
Signature · 1 line
2.18.0
PATCH v3 4/4 build: generate API documentation with Meson
In reply to 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
doc/api/generate_doxygen.sh new file +10 -0
@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
doc/api/meson.build new file +56 -0
56 lines not on this page · raw message
doc/build-sdk-meson.txt +2 -0
@@ -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
doc/meson.build new file +4 -0
@@ -0,0 +1,4 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +subdir('api')
meson.build +3 -0
@@ -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')
meson_options.txt +2 -0
@@ -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: '',
Signature · 1 line
2.18.0
Re: [PATCH v3 4/4] build: generate API documentation with Meson
Quoted 86 lines · Luca Boccassi
Signed-off-by Luca Boccassi <[email protected]>---
v2: made doxygen dependency optional, skip doxygen build when not found
v3: made doxygen dependency mandatory ifenable_docsis true, add
alternative doc target that prints "doxygen not found" when doxygen is not found andenable_docsis 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.builddoc/api/generate_doxygen.sh new file +10
-0@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.cssdoc/api/meson.build new file +46
-0@@ -0,0 +1,56 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +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,
doc/api/meson.build line 56
Quoted 10 lines
doc/api/meson.build new file +10
-0+ 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.
Re: [PATCH v3 4/4] build: generate API documentation with Meson
Quoted 96 lines · Bruce Richardson
Quoted 95 lines · Luca Boccassi
Signed-off-by Luca Boccassi <[email protected]>---
v2: made doxygen dependency optional, skip doxygen build when not found
v3: made doxygen dependency mandatory ifenable_docsis true, add
alternative doc target that prints "doxygen not found" when doxygen is not found andenable_docsis 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.builddoc/api/generate_doxygen.sh new file +10
-0@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.cssdoc/api/meson.build new file +55
-0@@ -0,0 +1,56 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +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'])
Quoted 8 lines
doc/api/meson.build line 56
Quoted 1 line
doc/api/meson.build new file +1
-0+endifWhile 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.
Re: [PATCH v3 4/4] build: generate API documentation with Meson
In reply to Bruce RichardsonQuoted 116 lines · Bruce Richardson
Quoted 110 lines · Luca Boccassi
Signed-off-by Luca Boccassi <[email protected]>---
v2: made doxygen dependency optional, skip doxygen build when not found
v3: made doxygen dependency mandatory ifenable_docsis true, add alternative doc target that prints "doxygen not found" when doxygen
is not found andenable_docsis 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.builddoc/api/generate_doxygen.sh new file +10
-0@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.cssdoc/api/meson.build new file +4
-0@@ -0,0 +1,56 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +doxygen = find_program('doxygen', required:
get_option('enable_docs'))doc/api/meson.build new file +3
-0+ +if doxygen.found() + # due to the CSS customisation script, which needs to runon a file that
doc/api/meson.build new file +1
-0+ # is in a subdirectory that is created at build time andthus it cannot
doc/api/meson.build new file +1
-0+ # be an individual custom_target, we need to wrap thedoxygen call in a
doc/api/meson.build new file +9
-0+ # 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
doc/api/meson.build new file +1
-0+ # if install is set to true it will override
build_by_defaultand it willdoc/api/meson.build new file +1
-0+ # cause the target to always be built. If install were tobe always set to
doc/api/meson.build new file +6
-0+ # 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@'],
doc/api/meson.build new file +7
-0+ 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'))
doc/api/meson.build new file +1
-0+ cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc','api'))
doc/api/meson.build new file +14
-0+ 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],doc/api/meson.build new file +7
-0+ 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',Quoted 2 lines
'found'])
+endifWhile I suggest we keep this in this patchset for now, this isn't going to
Quoted 8 lines
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?
Signature · 2 lines
Kind regards, Luca Boccassi
PATCH v4 1/4 mk: use script to generate examples.dox
In reply to Luca BoccassiThis will make it possible to generate the file in the same way from Meson as well.
---
v2: simplified script by using exec > file
v4: add acked-by
doc/api/generate_examples.sh | 12 ++++++++++++ mk/rte.sdkdoc.mk | 5 +---- 2 files changed, 13 insertions(+), 4 deletions(-) create mode 100755 doc/api/generate_examples.sh
doc/api/generate_examples.sh new file +12 -0
@@ -0,0 +1,12 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +EXAMPLES_DIR=$1 +API_EXAMPLES=$2 + +exec > "${API_EXAMPLES}" +printf '/**\n' +printf '@page examples DPDK Example Programs\n\n' +find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort +printf '*/\n'
mk/rte.sdkdoc.mk +1 -4
@@ -63,10 +63,7 @@ api-html-clean: $(API_EXAMPLES): api-html-clean $(Q)mkdir -p $(@D) - @printf '/**\n' > $(API_EXAMPLES) - @printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES) - @find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES) - @printf '*/\n' >> $(API_EXAMPLES) + $(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES) guides-pdf-clean: guides-pdf-img-clean guides-pdf-img-clean:
Signature · 1 line
2.18.0
PATCH v4 2/4 mk: use templated doxygen config, modified on the fly
This will allow the same config file to be used from Meson. The result has been verified to be identical via diffoscope.
---
v2: reordered generated fields as requested
v4: add acked-by
doc/api/doxy-api.conf | 87 ------------------------------------ doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++ mk/rte.sdkdoc.mk | 16 +++---- 3 files changed, 103 insertions(+), 96 deletions(-) delete mode 100644 doc/api/doxy-api.conf create mode 100644 doc/api/doxy-api.conf.in
doc/api/doxy-api.conf deleted +0 -87
@@ -1,87 +0,0 @@ -# SPDX-License-Identifier: BSD-3-Clause -# Copyright 2013-2017 6WIND S.A. - -PROJECT_NAME = DPDK -INPUT = doc/api/doxy-api-index.md \ - drivers/crypto/scheduler \ - drivers/mempool/dpaa2 \ - drivers/net/bnxt \ - drivers/net/bonding \ - drivers/net/dpaa \ - drivers/net/i40e \ - drivers/net/ixgbe \ - drivers/net/softnic \ - drivers/raw/dpaa2_cmdif \ - drivers/raw/dpaa2_qdma \ - lib/librte_eal/common/include \ - lib/librte_eal/common/include/generic \ - lib/librte_acl \ - lib/librte_bbdev \ - lib/librte_bitratestats \ - lib/librte_bpf \ - lib/librte_cfgfile \ - lib/librte_cmdline \ - lib/librte_compat \ - lib/librte_compressdev \ - lib/librte_cryptodev \ - lib/librte_distributor \ - lib/librte_efd \ - lib/librte_ethdev \ - lib/librte_eventdev \ - lib/librte_flow_classify \ - lib/librte_gro \ - lib/librte_gso \ - lib/librte_hash \ - lib/librte_ip_frag \ - lib/librte_jobstats \ - lib/librte_kni \ - lib/librte_kvargs \ - lib/librte_latencystats \ - lib/librte_lpm \ - lib/librte_mbuf \ - lib/librte_member \ - lib/librte_mempool \ - lib/librte_meter \ - lib/librte_metrics \ - lib/librte_net \ - lib/librte_pci \ - lib/librte_pdump \ - lib/librte_pipeline \ - lib/librte_port \ - lib/librte_power \ - lib/librte_rawdev \ - lib/librte_reorder \ - lib/librte_ring \ - lib/librte_sched \ - lib/librte_security \ - lib/librte_table \ - lib/librte_timer \ - lib/librte_vhost -FILE_PATTERNS = rte_*.h \ - cmdline.h -PREDEFINED = __DOXYGEN__ \ - VFIO_PRESENT \ - __attribute__(x)= - -OPTIMIZE_OUTPUT_FOR_C = YES -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -EXTRACT_STATIC = YES -DISTRIBUTE_GROUP_DOC = YES -HIDE_UNDOC_MEMBERS = YES -HIDE_UNDOC_CLASSES = YES -HIDE_SCOPE_NAMES = YES -GENERATE_DEPRECATEDLIST = NO -VERBATIM_HEADERS = NO -ALPHABETICAL_INDEX = NO - -HTML_TIMESTAMP = NO -HTML_DYNAMIC_SECTIONS = YES -SEARCHENGINE = NO -SORT_MEMBER_DOCS = NO -SOURCE_BROWSER = YES - -EXAMPLE_PATH = examples -EXAMPLE_PATTERNS = *.c -EXAMPLE_RECURSIVE = YES
doc/api/doxy-api.conf.in new file +96 -0
96 lines not on this page · raw message
mk/rte.sdkdoc.mk +7 -9
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean api-html: $(API_EXAMPLES) @echo 'doxygen for API...' $(Q)mkdir -p $(RTE_OUTPUT)/doc/html - $(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf && \ - printf 'PROJECT_NUMBER = ' && \ - $(MAKE) -rRs showversion && \ - echo INPUT += $(API_EXAMPLES) && \ - echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \ - echo HTML_OUTPUT = html/api && \ - echo GENERATE_HTML = YES && \ - echo GENERATE_LATEX = NO && \ - echo GENERATE_MAN = NO )| \ + $(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \ + -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|" \ + -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|" \ + -e "s|@HTML_OUTPUT@|html/api|" \ + -e "s|@TOPDIR@|./|g" \ + -e "s|@STRIP_FROM_PATH@|./|g" \ + $(RTE_SDK)/doc/api/doxy-api.conf.in)| \ doxygen - $(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
Signature · 1 line
2.18.0
PATCH v4 3/4 build: use same version as make showversion in Meson
In reply to Luca Boccassimake showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0, causing among other things a difference in the generated documentation.
---
v3: add acked-by
meson.build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
@@ -2,7 +2,7 @@ # Copyright(c) 2017 Intel Corporation project('DPDK', 'C', - version: '18.11-rc0', + version: '18.11.0-rc0', license: 'BSD', default_options: ['buildtype=release', 'default_library=static'], meson_version: '>= 0.41'
Signature · 1 line
2.18.0
PATCH v4 4/4 build: generate API documentation with Meson
In reply to 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)
v4: add acked-by
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
doc/api/generate_doxygen.sh new file +10 -0
@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
doc/api/meson.build new file +56 -0
56 lines not on this page · raw message
doc/build-sdk-meson.txt +2 -0
@@ -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
doc/meson.build new file +4 -0
@@ -0,0 +1,4 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +subdir('api')
meson.build +3 -0
@@ -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')
meson_options.txt +2 -0
@@ -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: '',
Signature · 1 line
2.18.0
PATCH v5 1/4 mk: use script to generate examples.dox
In reply to Luca BoccassiThis will make it possible to generate the file in the same way from Meson as well.
---
v2: simplified script by using exec > file
v4: add acked-by
doc/api/generate_examples.sh | 12 ++++++++++++ mk/rte.sdkdoc.mk | 5 +---- 2 files changed, 13 insertions(+), 4 deletions(-) create mode 100755 doc/api/generate_examples.sh
doc/api/generate_examples.sh new file +12 -0
@@ -0,0 +1,12 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +EXAMPLES_DIR=$1 +API_EXAMPLES=$2 + +exec > "${API_EXAMPLES}" +printf '/**\n' +printf '@page examples DPDK Example Programs\n\n' +find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort +printf '*/\n'
mk/rte.sdkdoc.mk +1 -4
@@ -63,10 +63,7 @@ api-html-clean: $(API_EXAMPLES): api-html-clean $(Q)mkdir -p $(@D) - @printf '/**\n' > $(API_EXAMPLES) - @printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES) - @find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES) - @printf '*/\n' >> $(API_EXAMPLES) + $(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES) guides-pdf-clean: guides-pdf-img-clean guides-pdf-img-clean:
Signature · 1 line
2.18.0
PATCH v5 2/4 mk: use templated doxygen config, modified on the fly
This will allow the same config file to be used from Meson. The result has been verified to be identical via diffoscope.
---
v2: reordered generated fields as requested
v4: add acked-by
doc/api/doxy-api.conf | 87 ------------------------------------ doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++ mk/rte.sdkdoc.mk | 16 +++---- 3 files changed, 103 insertions(+), 96 deletions(-) delete mode 100644 doc/api/doxy-api.conf create mode 100644 doc/api/doxy-api.conf.in
doc/api/doxy-api.conf deleted +0 -87
@@ -1,87 +0,0 @@ -# SPDX-License-Identifier: BSD-3-Clause -# Copyright 2013-2017 6WIND S.A. - -PROJECT_NAME = DPDK -INPUT = doc/api/doxy-api-index.md \ - drivers/crypto/scheduler \ - drivers/mempool/dpaa2 \ - drivers/net/bnxt \ - drivers/net/bonding \ - drivers/net/dpaa \ - drivers/net/i40e \ - drivers/net/ixgbe \ - drivers/net/softnic \ - drivers/raw/dpaa2_cmdif \ - drivers/raw/dpaa2_qdma \ - lib/librte_eal/common/include \ - lib/librte_eal/common/include/generic \ - lib/librte_acl \ - lib/librte_bbdev \ - lib/librte_bitratestats \ - lib/librte_bpf \ - lib/librte_cfgfile \ - lib/librte_cmdline \ - lib/librte_compat \ - lib/librte_compressdev \ - lib/librte_cryptodev \ - lib/librte_distributor \ - lib/librte_efd \ - lib/librte_ethdev \ - lib/librte_eventdev \ - lib/librte_flow_classify \ - lib/librte_gro \ - lib/librte_gso \ - lib/librte_hash \ - lib/librte_ip_frag \ - lib/librte_jobstats \ - lib/librte_kni \ - lib/librte_kvargs \ - lib/librte_latencystats \ - lib/librte_lpm \ - lib/librte_mbuf \ - lib/librte_member \ - lib/librte_mempool \ - lib/librte_meter \ - lib/librte_metrics \ - lib/librte_net \ - lib/librte_pci \ - lib/librte_pdump \ - lib/librte_pipeline \ - lib/librte_port \ - lib/librte_power \ - lib/librte_rawdev \ - lib/librte_reorder \ - lib/librte_ring \ - lib/librte_sched \ - lib/librte_security \ - lib/librte_table \ - lib/librte_timer \ - lib/librte_vhost -FILE_PATTERNS = rte_*.h \ - cmdline.h -PREDEFINED = __DOXYGEN__ \ - VFIO_PRESENT \ - __attribute__(x)= - -OPTIMIZE_OUTPUT_FOR_C = YES -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -EXTRACT_STATIC = YES -DISTRIBUTE_GROUP_DOC = YES -HIDE_UNDOC_MEMBERS = YES -HIDE_UNDOC_CLASSES = YES -HIDE_SCOPE_NAMES = YES -GENERATE_DEPRECATEDLIST = NO -VERBATIM_HEADERS = NO -ALPHABETICAL_INDEX = NO - -HTML_TIMESTAMP = NO -HTML_DYNAMIC_SECTIONS = YES -SEARCHENGINE = NO -SORT_MEMBER_DOCS = NO -SOURCE_BROWSER = YES - -EXAMPLE_PATH = examples -EXAMPLE_PATTERNS = *.c -EXAMPLE_RECURSIVE = YES
doc/api/doxy-api.conf.in new file +96 -0
96 lines not on this page · raw message
mk/rte.sdkdoc.mk +7 -9
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean api-html: $(API_EXAMPLES) @echo 'doxygen for API...' $(Q)mkdir -p $(RTE_OUTPUT)/doc/html - $(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf && \ - printf 'PROJECT_NUMBER = ' && \ - $(MAKE) -rRs showversion && \ - echo INPUT += $(API_EXAMPLES) && \ - echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \ - echo HTML_OUTPUT = html/api && \ - echo GENERATE_HTML = YES && \ - echo GENERATE_LATEX = NO && \ - echo GENERATE_MAN = NO )| \ + $(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \ + -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|" \ + -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|" \ + -e "s|@HTML_OUTPUT@|html/api|" \ + -e "s|@TOPDIR@|./|g" \ + -e "s|@STRIP_FROM_PATH@|./|g" \ + $(RTE_SDK)/doc/api/doxy-api.conf.in)| \ doxygen - $(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
Signature · 1 line
2.18.0
PATCH v5 3/4 build: use same version as make showversion in Meson
In reply to Luca Boccassimake showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0, causing among other things a difference in the generated documentation.
---
v3: add acked-by
meson.build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
@@ -2,7 +2,7 @@ # Copyright(c) 2017 Intel Corporation project('DPDK', 'C', - version: '18.11-rc0', + version: '18.11.0-rc0', license: 'BSD', default_options: ['buildtype=release', 'default_library=static'], meson_version: '>= 0.41'
Signature · 1 line
2.18.0
PATCH v5 4/4 build: generate API documentation with Meson
In reply to 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)
v4: add acked-by
v5: change install directory to $PREFIX/share/doc/dpdk to match legacy
makefiles
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
doc/api/generate_doxygen.sh new file +10 -0
@@ -0,0 +1,10 @@ +#! /bin/sh -e +# SPDX-License-Identifier: BSD-3-Clause +# Copyright 2018 Luca Boccassi <[email protected]> + +DOXYCONF=$1 +OUTDIR=$2 +SCRIPTCSS=$3 + +doxygen "${DOXYCONF}" +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
doc/api/meson.build new file +56 -0
56 lines not on this page · raw message
doc/build-sdk-meson.txt +2 -0
@@ -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
doc/meson.build new file +4 -0
@@ -0,0 +1,4 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2018 Luca Boccassi <[email protected]> + +subdir('api')
meson.build +3 -0
@@ -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')
meson_options.txt +2 -0
@@ -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: '',
Signature · 1 line
2.18.0
Re: [PATCH v5 4/4] build: generate API documentation with Meson
11/09/2018 22:42, Luca Boccassi:
Quoted 2 lines
Signed-off-by Luca Boccassi <[email protected]>Acked-by Bruce Richardson <[email protected]>
Series applied, thanks