Skip to contentSkip to conversation

Meson: build Doxygen documentation

PATCH Superseded Luca Boccassi 3 participants 39 messages Aug 31, 2018 – Sep 18, 2018 Arm/Amlogic Meson SoC support

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
new file mode 100755
index 0000000000..9633a64f7a
@@ -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
index bd2e5763df..d023b720fe 100644
@@ -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
#2 lore raw

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)?

#3 lore raw

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
#4 lore raw

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

#5 lore raw

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
#6 lore raw

PATCH 2/4 mk: use templated doxygen config, modified on the fly

In reply to Luca Boccassi

This 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
deleted file mode 100644
index 66693c3835..0000000000
@@ -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
index d023b720fe..c44db6447a 100644
@@ -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
#7 lore raw

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
#8 lore raw

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/g

eneric \
+                          @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

doc/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          = 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

Quoted 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
#9 lore raw

PATCH 3/4 build: use same version as make showversion in Meson

In reply to Luca Boccassi

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")
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
index 84af32ecef..9999e8640a 100644
@@ -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
#11 lore raw

PATCH 4/4 build: generate API documentation with Meson

In reply to 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.

---
 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
new file mode 100755
index 0000000000..ab57660958
@@ -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
index 9618e759ea..508e2cb642 100644
@@ -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
new file mode 100644
index 0000000000..afca2e7133
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <[email protected]>
+
+subdir('api')
meson.build +3 -0
index 9999e8640a..09506ec48c 100644
@@ -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
index f20887212a..d38ba56e29 100644
@@ -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
#12 lore raw

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.

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?

#13 lore raw

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.

---
 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.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?

Signature · 2 lines
Kind regards,
Luca Boccassi
#14 lore raw

Re: [PATCH 4/4] build: generate API documentation with Meson

In reply to Luca Boccassi
Quoted 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.

---
 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
new file mode 100755
index 0000000000..ab57660958
@@ -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 +1 -0
new file mode 100644
index 0000000000..e44963e4a9
@@ -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

#15 lore raw

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.

---
 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
new file mode 100755
index 0000000000..ab57660958
@@ -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 +4 -0
new file mode 100644
index 0000000000..e44963e4a9
@@ -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 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

doc/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
#16 lore raw

PATCH v2 1/4 mk: use script to generate examples.dox

In reply to Luca Boccassi

This 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
new file mode 100755
index 0000000000..6fcfe513b6
@@ -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
index bd2e5763df..d023b720fe 100644
@@ -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
#17 lore raw

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
deleted file mode 100644
index 66693c3835..0000000000
@@ -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
index d023b720fe..c44db6447a 100644
@@ -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
#18 lore raw

PATCH v2 3/4 build: use same version as make showversion in Meson

In reply to Luca Boccassi

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")
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
index 84af32ecef..9999e8640a 100644
@@ -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
#19 lore raw

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
new file mode 100755
index 0000000000..ab57660958
@@ -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
index 9618e759ea..508e2cb642 100644
@@ -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
new file mode 100644
index 0000000000..afca2e7133
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <[email protected]>
+
+subdir('api')
meson.build +3 -0
index 9999e8640a..09506ec48c 100644
@@ -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
index f20887212a..d38ba56e29 100644
@@ -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
#20 lore raw

Re: [PATCH v2 4/4] build: generate API documentation with Meson

Quoted 37 lines · 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
new file mode 100755
index 0000000000..ab57660958
@@ -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 +0 -0
new file mode 100644
index 0000000000..5dfa0fe044

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.

#21 lore raw

Re: [PATCH v2 4/4] build: generate API documentation with Meson

Quoted 42 lines · Bruce Richardson
Quoted 41 lines · 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
new file mode 100755
index 0000000000..ab57660958
@@ -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 +1 -0
new file mode 100644
index 0000000000..5dfa0fe044
@@ -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 run

on a file that

doc/api/meson.build new file +1 -0
+	# is in a subdirectory that is created at build time and

thus it cannot

doc/api/meson.build new file +1 -0
+	# be an individual custom_target, we need to wrap the

doxygen 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_default and it will

doc/api/meson.build new file +1 -0
+	# cause the target to always be built. If install were to

be 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)
+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.

Done

Signature · 2 lines
Kind regards,
Luca Boccassi
#23 lore raw

PATCH v3 1/4 mk: use script to generate examples.dox

In reply to Luca Boccassi

This 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
new file mode 100755
index 0000000000..6fcfe513b6
@@ -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
index bd2e5763df..d023b720fe 100644
@@ -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
#24 lore raw

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
deleted file mode 100644
index 66693c3835..0000000000
@@ -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
index d023b720fe..c44db6447a 100644
@@ -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
#25 lore raw

PATCH v3 3/4 build: use same version as make showversion in Meson

In reply to Luca Boccassi

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")
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
index 84af32ecef..9999e8640a 100644
@@ -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
#26 lore raw

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
new file mode 100755
index 0000000000..ab57660958
@@ -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
index 9618e759ea..508e2cb642 100644
@@ -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
new file mode 100644
index 0000000000..afca2e7133
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <[email protected]>
+
+subdir('api')
meson.build +3 -0
index 9999e8640a..09506ec48c 100644
@@ -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
index f20887212a..d38ba56e29 100644
@@ -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
#27 lore raw

Re: [PATCH v3 4/4] build: generate API documentation with Meson

Quoted 86 lines · 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
new file mode 100755
index 0000000000..ab57660958
@@ -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 +46 -0
new file mode 100644
index 0000000000..602fa7f3c3
@@ -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.

#28 lore raw

Re: [PATCH v3 4/4] build: generate API documentation with Meson

Quoted 96 lines · Bruce Richardson
Quoted 95 lines · 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
new file mode 100755
index 0000000000..ab57660958
@@ -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 +55 -0
new file mode 100644
index 0000000000..602fa7f3c3
@@ -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
+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.

#29 lore raw

Re: [PATCH v3 4/4] build: generate API documentation with Meson

In reply to Bruce Richardson
Quoted 116 lines · Bruce Richardson
Quoted 110 lines · 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
new file mode 100755
index 0000000000..ab57660958
@@ -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 +4 -0
new file mode 100644
index 0000000000..602fa7f3c3
@@ -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 run

on a file that

doc/api/meson.build new file +1 -0
+	# is in a subdirectory that is created at build time and

thus it cannot

doc/api/meson.build new file +1 -0
+	# be an individual custom_target, we need to wrap the

doxygen 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_default and it will

doc/api/meson.build new file +1 -0
+	# cause the target to always be built. If install were to

be 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'])
+endif

While 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
#30 lore raw

PATCH v4 1/4 mk: use script to generate examples.dox

In reply to Luca Boccassi

This 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
new file mode 100755
index 0000000000..6fcfe513b6
@@ -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
index bd2e5763df..d023b720fe 100644
@@ -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
#31 lore raw

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
deleted file mode 100644
index 66693c3835..0000000000
@@ -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
index d023b720fe..c44db6447a 100644
@@ -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
#32 lore raw

PATCH v4 3/4 build: use same version as make showversion in Meson

In reply to Luca Boccassi

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")

---
v3: add acked-by

 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
index 84af32ecef..9999e8640a 100644
@@ -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
#33 lore raw

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
new file mode 100755
index 0000000000..ab57660958
@@ -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
index 9618e759ea..508e2cb642 100644
@@ -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
new file mode 100644
index 0000000000..afca2e7133
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <[email protected]>
+
+subdir('api')
meson.build +3 -0
index 9999e8640a..09506ec48c 100644
@@ -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
index f20887212a..d38ba56e29 100644
@@ -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
#34 lore raw

PATCH v5 1/4 mk: use script to generate examples.dox

In reply to Luca Boccassi

This 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
new file mode 100755
index 0000000000..6fcfe513b6
@@ -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
index bd2e5763df..d023b720fe 100644
@@ -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
#35 lore raw

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
deleted file mode 100644
index 66693c3835..0000000000
@@ -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
index d023b720fe..c44db6447a 100644
@@ -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
#36 lore raw

PATCH v5 3/4 build: use same version as make showversion in Meson

In reply to Luca Boccassi

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")

---
v3: add acked-by

 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
index 84af32ecef..9999e8640a 100644
@@ -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
#37 lore raw

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
new file mode 100755
index 0000000000..ab57660958
@@ -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
index 9618e759ea..508e2cb642 100644
@@ -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
new file mode 100644
index 0000000000..afca2e7133
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <[email protected]>
+
+subdir('api')
meson.build +3 -0
index 9999e8640a..09506ec48c 100644
@@ -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
index f20887212a..d38ba56e29 100644
@@ -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