* [PATCH 0/3] doc: build on Windows
@ 2022-03-31 21:28 Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 1/3] doc: simplify CSS customization for Doxygen Dmitry Kozlyuk
` (3 more replies)
0 siblings, 4 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-03-31 21:28 UTC (permalink / raw)
To: dev; +Cc: Vipin Varghese, Dmitry Kozlyuk
Enable biulding documentation on Windows natively.
Thanks to Vipin for raising the issue.
Dmitry Kozlyuk (3):
doc: simplify CSS customization for Doxygen
doc: fix API index Markdown syntax
doc: rewrite shell scripts in Python
doc/api/custom.css | 6 +
doc/api/doxy-api-index.md | 366 +++++++++++++++++------------------
doc/api/doxy-api.conf.in | 1 +
doc/api/doxy-html-custom.sh | 8 -
doc/api/generate_doxygen.py | 19 ++
doc/api/generate_doxygen.sh | 15 --
doc/api/generate_examples.py | 31 +++
doc/api/generate_examples.sh | 20 --
doc/api/meson.build | 7 +-
9 files changed, 243 insertions(+), 230 deletions(-)
create mode 100644 doc/api/custom.css
delete mode 100755 doc/api/doxy-html-custom.sh
create mode 100644 doc/api/generate_doxygen.py
delete mode 100755 doc/api/generate_doxygen.sh
create mode 100644 doc/api/generate_examples.py
delete mode 100755 doc/api/generate_examples.sh
--
2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH 1/3] doc: simplify CSS customization for Doxygen
2022-03-31 21:28 [PATCH 0/3] doc: build on Windows Dmitry Kozlyuk
@ 2022-03-31 21:28 ` Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 2/3] doc: fix API index Markdown syntax Dmitry Kozlyuk
` (2 subsequent siblings)
3 siblings, 0 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-03-31 21:28 UTC (permalink / raw)
To: dev; +Cc: Vipin Varghese, Dmitry Kozlyuk
CSS for API documentation was customized by a shell script
modifying the file that Doxygen produces.
This way CSS code is kept in a script and an extra build step is added.
Move custom style to a plain CSS file.
Use Doxygen capability to attach this extra stylesheet.
Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
---
doc/api/custom.css | 6 ++++++
doc/api/doxy-api.conf.in | 1 +
doc/api/doxy-html-custom.sh | 8 --------
doc/api/generate_doxygen.sh | 3 ---
doc/api/meson.build | 3 +--
5 files changed, 8 insertions(+), 13 deletions(-)
create mode 100644 doc/api/custom.css
delete mode 100755 doc/api/doxy-html-custom.sh
diff --git a/doc/api/custom.css b/doc/api/custom.css
new file mode 100644
index 0000000000..66360f9b48
--- /dev/null
+++ b/doc/api/custom.css
@@ -0,0 +1,6 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright 2013 6WIND S.A.
+ */
+
+/* space between item and its comment */
+dd td:first-child { padding-right: 2em; }
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index db2ca9b6ed..8e961cbc8c 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -102,6 +102,7 @@ ALPHABETICAL_INDEX = NO
HTML_TIMESTAMP = NO
HTML_DYNAMIC_SECTIONS = YES
+HTML_EXTRA_STYLESHEET = @TOPDIR@/doc/api/custom.css
SEARCHENGINE = YES
SORT_MEMBER_DOCS = NO
SOURCE_BROWSER = YES
diff --git a/doc/api/doxy-html-custom.sh b/doc/api/doxy-html-custom.sh
deleted file mode 100755
index 3802007c8c..0000000000
--- a/doc/api/doxy-html-custom.sh
+++ /dev/null
@@ -1,8 +0,0 @@
-#! /bin/sh -e
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2013 6WIND S.A.
-
-CSS=$1
-
-# space between item and its comment
-echo 'dd td:first-child {padding-right: 2em;}' >> $CSS
diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
index 1350e50491..1940ea46e2 100755
--- a/doc/api/generate_doxygen.sh
+++ b/doc/api/generate_doxygen.sh
@@ -4,12 +4,9 @@
DOXYCONF=$1
OUTDIR=$2
-SCRIPTCSS=$3
OUT_FILE=$(dirname $OUTDIR)/doxygen.out
# run doxygen, capturing all the header files it processed
doxygen "${DOXYCONF}" > $OUT_FILE
echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' $OUT_FILE)" > $OUTDIR.d
-
-"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
diff --git a/doc/api/meson.build b/doc/api/meson.build
index 5c25b92092..53338a02d6 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -13,7 +13,6 @@ endif
# 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')
htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')
@@ -52,7 +51,7 @@ doxy_build = custom_target('doxygen',
input: doxy_conf,
output: 'html',
depfile: 'html.d',
- command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
+ command: [generate_doxygen, '@INPUT@', '@OUTPUT@'],
install: get_option('enable_docs'),
install_dir: htmldir,
build_by_default: get_option('enable_docs'))
--
2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH 2/3] doc: fix API index Markdown syntax
2022-03-31 21:28 [PATCH 0/3] doc: build on Windows Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 1/3] doc: simplify CSS customization for Doxygen Dmitry Kozlyuk
@ 2022-03-31 21:28 ` Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 3/3] doc: rewrite shell scripts in Python Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 0/3] doc: build on Windows Dmitry Kozlyuk
3 siblings, 0 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-03-31 21:28 UTC (permalink / raw)
To: dev
Cc: Vipin Varghese, Dmitry Kozlyuk, Olivier Matz, Thomas Monjalon,
David Marchand
API documentation index had spaces between link caption and URL,
which may be unsupported by some Markdown implementations.
That is, "[caption](URL)" is valid but "[caption] (URL)" is not.
The problematic behavior is observed with Doxygen on Windows.
Remove the spaces.
Unfortunately, Markdown syntax is not formally specified.
Fixes: 9bf486e606b0 ("doc: generate HTML for API with doxygen")
Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
---
I believe there's no need for this patch in stable releases,
because it was never an issue until an attempt to build on Windows.
doc/api/doxy-api-index.md | 366 +++++++++++++++++++-------------------
1 file changed, 183 insertions(+), 183 deletions(-)
diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index 4245b9635c..baecb2e52e 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -9,222 +9,222 @@ API
The public API headers are grouped by topics:
- **device**:
- [dev] (@ref rte_dev.h),
- [ethdev] (@ref rte_ethdev.h),
- [ethctrl] (@ref rte_eth_ctrl.h),
- [rte_flow] (@ref rte_flow.h),
- [rte_tm] (@ref rte_tm.h),
- [rte_mtr] (@ref rte_mtr.h),
- [bbdev] (@ref rte_bbdev.h),
- [cryptodev] (@ref rte_cryptodev.h),
- [security] (@ref rte_security.h),
- [compressdev] (@ref rte_compressdev.h),
- [compress] (@ref rte_comp.h),
- [regexdev] (@ref rte_regexdev.h),
- [dmadev] (@ref rte_dmadev.h),
- [eventdev] (@ref rte_eventdev.h),
- [event_eth_rx_adapter] (@ref rte_event_eth_rx_adapter.h),
- [event_eth_tx_adapter] (@ref rte_event_eth_tx_adapter.h),
- [event_timer_adapter] (@ref rte_event_timer_adapter.h),
- [event_crypto_adapter] (@ref rte_event_crypto_adapter.h),
- [rawdev] (@ref rte_rawdev.h),
- [metrics] (@ref rte_metrics.h),
- [bitrate] (@ref rte_bitrate.h),
- [latency] (@ref rte_latencystats.h),
- [devargs] (@ref rte_devargs.h),
- [PCI] (@ref rte_pci.h),
- [vdev] (@ref rte_bus_vdev.h),
- [vfio] (@ref rte_vfio.h)
+ [dev](@ref rte_dev.h),
+ [ethdev](@ref rte_ethdev.h),
+ [ethctrl](@ref rte_eth_ctrl.h),
+ [rte_flow](@ref rte_flow.h),
+ [rte_tm](@ref rte_tm.h),
+ [rte_mtr](@ref rte_mtr.h),
+ [bbdev](@ref rte_bbdev.h),
+ [cryptodev](@ref rte_cryptodev.h),
+ [security](@ref rte_security.h),
+ [compressdev](@ref rte_compressdev.h),
+ [compress](@ref rte_comp.h),
+ [regexdev](@ref rte_regexdev.h),
+ [dmadev](@ref rte_dmadev.h),
+ [eventdev](@ref rte_eventdev.h),
+ [event_eth_rx_adapter](@ref rte_event_eth_rx_adapter.h),
+ [event_eth_tx_adapter](@ref rte_event_eth_tx_adapter.h),
+ [event_timer_adapter](@ref rte_event_timer_adapter.h),
+ [event_crypto_adapter](@ref rte_event_crypto_adapter.h),
+ [rawdev](@ref rte_rawdev.h),
+ [metrics](@ref rte_metrics.h),
+ [bitrate](@ref rte_bitrate.h),
+ [latency](@ref rte_latencystats.h),
+ [devargs](@ref rte_devargs.h),
+ [PCI](@ref rte_pci.h),
+ [vdev](@ref rte_bus_vdev.h),
+ [vfio](@ref rte_vfio.h)
- **device specific**:
- [softnic] (@ref rte_eth_softnic.h),
- [bond] (@ref rte_eth_bond.h),
- [vhost] (@ref rte_vhost.h),
- [vdpa] (@ref rte_vdpa.h),
- [KNI] (@ref rte_kni.h),
- [ixgbe] (@ref rte_pmd_ixgbe.h),
- [i40e] (@ref rte_pmd_i40e.h),
- [ice] (@ref rte_pmd_ice.h),
- [iavf] (@ref rte_pmd_iavf.h),
- [ioat] (@ref rte_ioat_rawdev.h),
- [bnxt] (@ref rte_pmd_bnxt.h),
- [dpaa] (@ref rte_pmd_dpaa.h),
- [dpaa2] (@ref rte_pmd_dpaa2.h),
- [mlx5] (@ref rte_pmd_mlx5.h),
- [dpaa2_mempool] (@ref rte_dpaa2_mempool.h),
- [dpaa2_cmdif] (@ref rte_pmd_dpaa2_cmdif.h),
- [dpaa2_qdma] (@ref rte_pmd_dpaa2_qdma.h),
- [crypto_scheduler] (@ref rte_cryptodev_scheduler.h),
- [dlb2] (@ref rte_pmd_dlb2.h),
- [ifpga] (@ref rte_pmd_ifpga.h)
+ [softnic](@ref rte_eth_softnic.h),
+ [bond](@ref rte_eth_bond.h),
+ [vhost](@ref rte_vhost.h),
+ [vdpa](@ref rte_vdpa.h),
+ [KNI](@ref rte_kni.h),
+ [ixgbe](@ref rte_pmd_ixgbe.h),
+ [i40e](@ref rte_pmd_i40e.h),
+ [ice](@ref rte_pmd_ice.h),
+ [iavf](@ref rte_pmd_iavf.h),
+ [ioat](@ref rte_ioat_rawdev.h),
+ [bnxt](@ref rte_pmd_bnxt.h),
+ [dpaa](@ref rte_pmd_dpaa.h),
+ [dpaa2](@ref rte_pmd_dpaa2.h),
+ [mlx5](@ref rte_pmd_mlx5.h),
+ [dpaa2_mempool](@ref rte_dpaa2_mempool.h),
+ [dpaa2_cmdif](@ref rte_pmd_dpaa2_cmdif.h),
+ [dpaa2_qdma](@ref rte_pmd_dpaa2_qdma.h),
+ [crypto_scheduler](@ref rte_cryptodev_scheduler.h),
+ [dlb2](@ref rte_pmd_dlb2.h),
+ [ifpga](@ref rte_pmd_ifpga.h)
- **memory**:
- [memseg] (@ref rte_memory.h),
- [memzone] (@ref rte_memzone.h),
- [mempool] (@ref rte_mempool.h),
- [malloc] (@ref rte_malloc.h),
- [memcpy] (@ref rte_memcpy.h)
+ [memseg](@ref rte_memory.h),
+ [memzone](@ref rte_memzone.h),
+ [mempool](@ref rte_mempool.h),
+ [malloc](@ref rte_malloc.h),
+ [memcpy](@ref rte_memcpy.h)
- **timers**:
- [cycles] (@ref rte_cycles.h),
- [timer] (@ref rte_timer.h),
- [alarm] (@ref rte_alarm.h)
+ [cycles](@ref rte_cycles.h),
+ [timer](@ref rte_timer.h),
+ [alarm](@ref rte_alarm.h)
- **locks**:
- [atomic] (@ref rte_atomic.h),
- [mcslock] (@ref rte_mcslock.h),
- [pflock] (@ref rte_pflock.h),
- [rwlock] (@ref rte_rwlock.h),
- [spinlock] (@ref rte_spinlock.h),
- [ticketlock] (@ref rte_ticketlock.h),
- [RCU] (@ref rte_rcu_qsbr.h)
+ [atomic](@ref rte_atomic.h),
+ [mcslock](@ref rte_mcslock.h),
+ [pflock](@ref rte_pflock.h),
+ [rwlock](@ref rte_rwlock.h),
+ [spinlock](@ref rte_spinlock.h),
+ [ticketlock](@ref rte_ticketlock.h),
+ [RCU](@ref rte_rcu_qsbr.h)
- **CPU arch**:
- [branch prediction] (@ref rte_branch_prediction.h),
- [cache prefetch] (@ref rte_prefetch.h),
- [SIMD] (@ref rte_vect.h),
- [byte order] (@ref rte_byteorder.h),
- [CPU flags] (@ref rte_cpuflags.h),
- [CPU pause] (@ref rte_pause.h),
- [I/O access] (@ref rte_io.h),
- [power management] (@ref rte_power_intrinsics.h)
+ [branch prediction](@ref rte_branch_prediction.h),
+ [cache prefetch](@ref rte_prefetch.h),
+ [SIMD](@ref rte_vect.h),
+ [byte order](@ref rte_byteorder.h),
+ [CPU flags](@ref rte_cpuflags.h),
+ [CPU pause](@ref rte_pause.h),
+ [I/O access](@ref rte_io.h),
+ [power management](@ref rte_power_intrinsics.h)
- **CPU multicore**:
- [interrupts] (@ref rte_interrupts.h),
- [launch] (@ref rte_launch.h),
- [lcore] (@ref rte_lcore.h),
- [per-lcore] (@ref rte_per_lcore.h),
- [service cores] (@ref rte_service.h),
- [keepalive] (@ref rte_keepalive.h),
- [power/freq] (@ref rte_power.h),
- [PMD power] (@ref rte_power_pmd_mgmt.h)
+ [interrupts](@ref rte_interrupts.h),
+ [launch](@ref rte_launch.h),
+ [lcore](@ref rte_lcore.h),
+ [per-lcore](@ref rte_per_lcore.h),
+ [service cores](@ref rte_service.h),
+ [keepalive](@ref rte_keepalive.h),
+ [power/freq](@ref rte_power.h),
+ [PMD power](@ref rte_power_pmd_mgmt.h)
- **layers**:
- [ethernet] (@ref rte_ether.h),
- [ARP] (@ref rte_arp.h),
- [HIGIG] (@ref rte_higig.h),
- [ICMP] (@ref rte_icmp.h),
- [ESP] (@ref rte_esp.h),
- [IPsec] (@ref rte_ipsec.h),
- [IPsec group] (@ref rte_ipsec_group.h),
- [IPsec SA] (@ref rte_ipsec_sa.h),
- [IPsec SAD] (@ref rte_ipsec_sad.h),
- [IP] (@ref rte_ip.h),
- [frag/reass] (@ref rte_ip_frag.h),
- [SCTP] (@ref rte_sctp.h),
- [TCP] (@ref rte_tcp.h),
- [UDP] (@ref rte_udp.h),
- [GTP] (@ref rte_gtp.h),
- [GRO] (@ref rte_gro.h),
- [GSO] (@ref rte_gso.h),
- [GRE] (@ref rte_gre.h),
- [MPLS] (@ref rte_mpls.h),
- [VXLAN] (@ref rte_vxlan.h),
- [Geneve] (@ref rte_geneve.h),
- [eCPRI] (@ref rte_ecpri.h),
- [L2TPv2] (@ref rte_l2tpv2.h),
- [PPP] (@ref rte_ppp.h)
+ [ethernet](@ref rte_ether.h),
+ [ARP](@ref rte_arp.h),
+ [HIGIG](@ref rte_higig.h),
+ [ICMP](@ref rte_icmp.h),
+ [ESP](@ref rte_esp.h),
+ [IPsec](@ref rte_ipsec.h),
+ [IPsec group](@ref rte_ipsec_group.h),
+ [IPsec SA](@ref rte_ipsec_sa.h),
+ [IPsec SAD](@ref rte_ipsec_sad.h),
+ [IP](@ref rte_ip.h),
+ [frag/reass](@ref rte_ip_frag.h),
+ [SCTP](@ref rte_sctp.h),
+ [TCP](@ref rte_tcp.h),
+ [UDP](@ref rte_udp.h),
+ [GTP](@ref rte_gtp.h),
+ [GRO](@ref rte_gro.h),
+ [GSO](@ref rte_gso.h),
+ [GRE](@ref rte_gre.h),
+ [MPLS](@ref rte_mpls.h),
+ [VXLAN](@ref rte_vxlan.h),
+ [Geneve](@ref rte_geneve.h),
+ [eCPRI](@ref rte_ecpri.h),
+ [L2TPv2](@ref rte_l2tpv2.h),
+ [PPP](@ref rte_ppp.h)
- **QoS**:
- [metering] (@ref rte_meter.h),
- [scheduler] (@ref rte_sched.h),
- [RED congestion] (@ref rte_red.h)
+ [metering](@ref rte_meter.h),
+ [scheduler](@ref rte_sched.h),
+ [RED congestion](@ref rte_red.h)
- **routing**:
- [LPM IPv4 route] (@ref rte_lpm.h),
- [LPM IPv6 route] (@ref rte_lpm6.h),
- [RIB IPv4] (@ref rte_rib.h),
- [RIB IPv6] (@ref rte_rib6.h),
- [FIB IPv4] (@ref rte_fib.h),
- [FIB IPv6] (@ref rte_fib6.h)
+ [LPM IPv4 route](@ref rte_lpm.h),
+ [LPM IPv6 route](@ref rte_lpm6.h),
+ [RIB IPv4](@ref rte_rib.h),
+ [RIB IPv6](@ref rte_rib6.h),
+ [FIB IPv4](@ref rte_fib.h),
+ [FIB IPv6](@ref rte_fib6.h)
- **hashes**:
- [hash] (@ref rte_hash.h),
- [jhash] (@ref rte_jhash.h),
- [thash] (@ref rte_thash.h),
- [thash_gfni] (@ref rte_thash_gfni.h),
- [FBK hash] (@ref rte_fbk_hash.h),
- [CRC hash] (@ref rte_hash_crc.h)
+ [hash](@ref rte_hash.h),
+ [jhash](@ref rte_jhash.h),
+ [thash](@ref rte_thash.h),
+ [thash_gfni](@ref rte_thash_gfni.h),
+ [FBK hash](@ref rte_fbk_hash.h),
+ [CRC hash](@ref rte_hash_crc.h)
- **classification**
- [reorder] (@ref rte_reorder.h),
- [distributor] (@ref rte_distributor.h),
- [EFD] (@ref rte_efd.h),
- [ACL] (@ref rte_acl.h),
- [member] (@ref rte_member.h),
- [flow classify] (@ref rte_flow_classify.h),
- [BPF] (@ref rte_bpf.h)
+ [reorder](@ref rte_reorder.h),
+ [distributor](@ref rte_distributor.h),
+ [EFD](@ref rte_efd.h),
+ [ACL](@ref rte_acl.h),
+ [member](@ref rte_member.h),
+ [flow classify](@ref rte_flow_classify.h),
+ [BPF](@ref rte_bpf.h)
- **containers**:
- [mbuf] (@ref rte_mbuf.h),
- [mbuf pool ops] (@ref rte_mbuf_pool_ops.h),
- [ring] (@ref rte_ring.h),
- [stack] (@ref rte_stack.h),
- [tailq] (@ref rte_tailq.h),
- [bitmap] (@ref rte_bitmap.h)
+ [mbuf](@ref rte_mbuf.h),
+ [mbuf pool ops](@ref rte_mbuf_pool_ops.h),
+ [ring](@ref rte_ring.h),
+ [stack](@ref rte_stack.h),
+ [tailq](@ref rte_tailq.h),
+ [bitmap](@ref rte_bitmap.h)
- **packet framework**:
- * [port] (@ref rte_port.h):
- [ethdev] (@ref rte_port_ethdev.h),
- [ring] (@ref rte_port_ring.h),
- [frag] (@ref rte_port_frag.h),
- [reass] (@ref rte_port_ras.h),
- [sched] (@ref rte_port_sched.h),
- [kni] (@ref rte_port_kni.h),
- [src/sink] (@ref rte_port_source_sink.h)
- * [table] (@ref rte_table.h):
- [lpm IPv4] (@ref rte_table_lpm.h),
- [lpm IPv6] (@ref rte_table_lpm_ipv6.h),
- [ACL] (@ref rte_table_acl.h),
- [hash] (@ref rte_table_hash.h),
- [array] (@ref rte_table_array.h),
- [stub] (@ref rte_table_stub.h)
- * [pipeline] (@ref rte_pipeline.h)
- [port_in_action] (@ref rte_port_in_action.h)
- [table_action] (@ref rte_table_action.h)
+ * [port](@ref rte_port.h):
+ [ethdev](@ref rte_port_ethdev.h),
+ [ring](@ref rte_port_ring.h),
+ [frag](@ref rte_port_frag.h),
+ [reass](@ref rte_port_ras.h),
+ [sched](@ref rte_port_sched.h),
+ [kni](@ref rte_port_kni.h),
+ [src/sink](@ref rte_port_source_sink.h)
+ * [table](@ref rte_table.h):
+ [lpm IPv4](@ref rte_table_lpm.h),
+ [lpm IPv6](@ref rte_table_lpm_ipv6.h),
+ [ACL](@ref rte_table_acl.h),
+ [hash](@ref rte_table_hash.h),
+ [array](@ref rte_table_array.h),
+ [stub](@ref rte_table_stub.h)
+ * [pipeline](@ref rte_pipeline.h)
+ [port_in_action](@ref rte_port_in_action.h)
+ [table_action](@ref rte_table_action.h)
* SWX pipeline:
- [control] (@ref rte_swx_ctl.h),
- [extern] (@ref rte_swx_extern.h),
- [pipeline] (@ref rte_swx_pipeline.h)
+ [control](@ref rte_swx_ctl.h),
+ [extern](@ref rte_swx_extern.h),
+ [pipeline](@ref rte_swx_pipeline.h)
* SWX port:
- [port] (@ref rte_swx_port.h),
- [ethdev] (@ref rte_swx_port_ethdev.h),
- [fd] (@ref rte_swx_port_fd.h),
- [ring] (@ref rte_swx_port_ring.h),
- [src/sink] (@ref rte_swx_port_source_sink.h)
+ [port](@ref rte_swx_port.h),
+ [ethdev](@ref rte_swx_port_ethdev.h),
+ [fd](@ref rte_swx_port_fd.h),
+ [ring](@ref rte_swx_port_ring.h),
+ [src/sink](@ref rte_swx_port_source_sink.h)
* SWX table:
- [table] (@ref rte_swx_table.h),
- [table_em] (@ref rte_swx_table_em.h)
- [table_wm] (@ref rte_swx_table_wm.h)
- * [graph] (@ref rte_graph.h):
- [graph_worker] (@ref rte_graph_worker.h)
+ [table](@ref rte_swx_table.h),
+ [table_em](@ref rte_swx_table_em.h)
+ [table_wm](@ref rte_swx_table_wm.h)
+ * [graph](@ref rte_graph.h):
+ [graph_worker](@ref rte_graph_worker.h)
* graph_nodes:
- [eth_node] (@ref rte_node_eth_api.h),
- [ip4_node] (@ref rte_node_ip4_api.h)
+ [eth_node](@ref rte_node_eth_api.h),
+ [ip4_node](@ref rte_node_ip4_api.h)
- **basic**:
- [bitops] (@ref rte_bitops.h),
- [approx fraction] (@ref rte_approx.h),
- [random] (@ref rte_random.h),
- [config file] (@ref rte_cfgfile.h),
- [key/value args] (@ref rte_kvargs.h),
- [string] (@ref rte_string_fns.h)
+ [bitops](@ref rte_bitops.h),
+ [approx fraction](@ref rte_approx.h),
+ [random](@ref rte_random.h),
+ [config file](@ref rte_cfgfile.h),
+ [key/value args](@ref rte_kvargs.h),
+ [string](@ref rte_string_fns.h)
- **debug**:
- [jobstats] (@ref rte_jobstats.h),
- [telemetry] (@ref rte_telemetry.h),
- [pcapng] (@ref rte_pcapng.h),
- [pdump] (@ref rte_pdump.h),
- [hexdump] (@ref rte_hexdump.h),
- [debug] (@ref rte_debug.h),
- [log] (@ref rte_log.h),
- [errno] (@ref rte_errno.h),
- [trace] (@ref rte_trace.h),
- [trace_point] (@ref rte_trace_point.h)
+ [jobstats](@ref rte_jobstats.h),
+ [telemetry](@ref rte_telemetry.h),
+ [pcapng](@ref rte_pcapng.h),
+ [pdump](@ref rte_pdump.h),
+ [hexdump](@ref rte_hexdump.h),
+ [debug](@ref rte_debug.h),
+ [log](@ref rte_log.h),
+ [errno](@ref rte_errno.h),
+ [trace](@ref rte_trace.h),
+ [trace_point](@ref rte_trace_point.h)
- **misc**:
- [EAL config] (@ref rte_eal.h),
- [common] (@ref rte_common.h),
- [experimental APIs] (@ref rte_compat.h),
- [ABI versioning] (@ref rte_function_versioning.h),
- [version] (@ref rte_version.h)
+ [EAL config](@ref rte_eal.h),
+ [common](@ref rte_common.h),
+ [experimental APIs](@ref rte_compat.h),
+ [ABI versioning](@ref rte_function_versioning.h),
+ [version](@ref rte_version.h)
--
2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH 3/3] doc: rewrite shell scripts in Python
2022-03-31 21:28 [PATCH 0/3] doc: build on Windows Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 1/3] doc: simplify CSS customization for Doxygen Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 2/3] doc: fix API index Markdown syntax Dmitry Kozlyuk
@ 2022-03-31 21:28 ` Dmitry Kozlyuk
2022-04-01 16:31 ` Bruce Richardson
2022-04-06 17:10 ` [PATCH v2 0/3] doc: build on Windows Dmitry Kozlyuk
3 siblings, 1 reply; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-03-31 21:28 UTC (permalink / raw)
To: dev; +Cc: Vipin Varghese, Dmitry Kozlyuk
Shell used in documentation generation could not run on Windows.
Rewrite scripts in Python.
New scripts use proper path separators and handle paths with spaces.
Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
---
doc/api/generate_doxygen.py | 19 +++++++++++++++++++
doc/api/generate_doxygen.sh | 12 ------------
doc/api/generate_examples.py | 31 +++++++++++++++++++++++++++++++
doc/api/generate_examples.sh | 20 --------------------
doc/api/meson.build | 6 +++---
5 files changed, 53 insertions(+), 35 deletions(-)
create mode 100644 doc/api/generate_doxygen.py
delete mode 100755 doc/api/generate_doxygen.sh
create mode 100644 doc/api/generate_examples.py
delete mode 100755 doc/api/generate_examples.sh
diff --git a/doc/api/generate_doxygen.py b/doc/api/generate_doxygen.py
new file mode 100644
index 0000000000..2ccedf844e
--- /dev/null
+++ b/doc/api/generate_doxygen.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# (c) 2018 Luca Boccassi <bluca@debian.org>
+# (c) 2022 Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
+
+import os, re, subprocess, sys
+
+pattern = re.compile('^Preprocessing (.*)...$')
+out_dir, *doxygen_command = sys.argv[1:]
+out_file = os.path.join(os.path.dirname(out_dir), 'doxygen.out')
+dep_file = f'{out_dir}.d'
+with open(out_file, 'w') as out:
+ subprocess.run(doxygen_command, check=True, stdout=out)
+with open(out_file) as out, open(dep_file, 'w') as dep:
+ print(f'{out_dir}:', end=' ', file=dep)
+ for line in out:
+ match = re.match(pattern, line)
+ if match:
+ print(match.group(1), end=' ', file=dep)
diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
deleted file mode 100755
index 1940ea46e2..0000000000
--- a/doc/api/generate_doxygen.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#! /bin/sh -e
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2018 Luca Boccassi <bluca@debian.org>
-
-DOXYCONF=$1
-OUTDIR=$2
-
-OUT_FILE=$(dirname $OUTDIR)/doxygen.out
-
-# run doxygen, capturing all the header files it processed
-doxygen "${DOXYCONF}" > $OUT_FILE
-echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' $OUT_FILE)" > $OUTDIR.d
diff --git a/doc/api/generate_examples.py b/doc/api/generate_examples.py
new file mode 100644
index 0000000000..66933f9472
--- /dev/null
+++ b/doc/api/generate_examples.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# (c) 2018 Luca Boccassi <bluca@debian.org>
+# (c) 2022 Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
+
+import os, sys
+
+examples_dir, api_examples = sys.argv[1:]
+
+sources = []
+with open(f'{api_examples}.d', 'w') as dep:
+ print(f'{api_examples}:', end=' ', file=dep)
+ for root, _, files in os.walk(examples_dir):
+ for name in files:
+ is_source = name.endswith('.c')
+ if is_source or name == 'meson.meson.build':
+ path = os.path.join(root, name)
+ if is_source:
+ sources.append(path)
+ print(path , end=' ', file=dep)
+
+sys.stdout = open(api_examples, 'w')
+print('/**')
+print('@page examples DPDK Example Programs')
+print()
+for path in sources:
+ # Produce consistent output with forward slashes on all systems.
+ # Every \ in paths within examples directory is a separator, not escape.
+ relpath = os.path.relpath(path, examples_dir).replace('\\', '/')
+ print(f'@example examples/{relpath}')
+print('*/')
diff --git a/doc/api/generate_examples.sh b/doc/api/generate_examples.sh
deleted file mode 100755
index 48574563ca..0000000000
--- a/doc/api/generate_examples.sh
+++ /dev/null
@@ -1,20 +0,0 @@
-#! /bin/sh -e
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2018 Luca Boccassi <bluca@debian.org>
-
-EXAMPLES_DIR=$1
-API_EXAMPLES=$2
-
-FIND=find
-
-# generate a .d file including both C files and also build files, so we can
-# detect both file changes and file additions/deletions
-echo "$API_EXAMPLES: $($FIND ${EXAMPLES_DIR} -type f \( -name '*.c' -o -name 'meson.build' \) | tr '\n' ' ' )" > ${API_EXAMPLES}.d
-
-exec > "${API_EXAMPLES}"
-printf '/**\n'
-printf '@page examples DPDK Example Programs\n\n'
-$FIND "${EXAMPLES_DIR}" -type f -name '*.c' |
- sed "s|${EXAMPLES_DIR}|@example examples|" |
- LC_ALL=C sort
-printf '*/\n'
diff --git a/doc/api/meson.build b/doc/api/meson.build
index 53338a02d6..2876a78a7e 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -11,8 +11,8 @@ endif
# 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_doxygen = py3 + files('generate_doxygen.py')
+generate_examples = py3 + files('generate_examples.py')
htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')
@@ -51,7 +51,7 @@ doxy_build = custom_target('doxygen',
input: doxy_conf,
output: 'html',
depfile: 'html.d',
- command: [generate_doxygen, '@INPUT@', '@OUTPUT@'],
+ command: [generate_doxygen, '@OUTPUT@', doxygen, '@INPUT@'],
install: get_option('enable_docs'),
install_dir: htmldir,
build_by_default: get_option('enable_docs'))
--
2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH 3/3] doc: rewrite shell scripts in Python
2022-03-31 21:28 ` [PATCH 3/3] doc: rewrite shell scripts in Python Dmitry Kozlyuk
@ 2022-04-01 16:31 ` Bruce Richardson
2022-04-01 21:47 ` Dmitry Kozlyuk
0 siblings, 1 reply; 13+ messages in thread
From: Bruce Richardson @ 2022-04-01 16:31 UTC (permalink / raw)
To: Dmitry Kozlyuk; +Cc: dev, Vipin Varghese
On Fri, Apr 01, 2022 at 12:28:30AM +0300, Dmitry Kozlyuk wrote:
> Shell used in documentation generation could not run on Windows.
> Rewrite scripts in Python.
> New scripts use proper path separators and handle paths with spaces.
>
> Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
> ---
Generally looks ok to me, couple of minor comments inline below.
Reviewed-by: Bruce Richardson <bruce.richardson@intel.com>
> doc/api/generate_doxygen.py | 19 +++++++++++++++++++
> doc/api/generate_doxygen.sh | 12 ------------
> doc/api/generate_examples.py | 31 +++++++++++++++++++++++++++++++
> doc/api/generate_examples.sh | 20 --------------------
> doc/api/meson.build | 6 +++---
> 5 files changed, 53 insertions(+), 35 deletions(-)
> create mode 100644 doc/api/generate_doxygen.py
> delete mode 100755 doc/api/generate_doxygen.sh
> create mode 100644 doc/api/generate_examples.py
> delete mode 100755 doc/api/generate_examples.sh
>
<snip>
> diff --git a/doc/api/generate_examples.py b/doc/api/generate_examples.py
> new file mode 100644
> index 0000000000..66933f9472
> --- /dev/null
> +++ b/doc/api/generate_examples.py
> @@ -0,0 +1,31 @@
> +#!/usr/bin/env python3
> +# SPDX-License-Identifier: BSD-3-Clause
> +# (c) 2018 Luca Boccassi <bluca@debian.org>
> +# (c) 2022 Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
> +
> +import os, sys
> +
> +examples_dir, api_examples = sys.argv[1:]
> +
> +sources = []
> +with open(f'{api_examples}.d', 'w') as dep:
> + print(f'{api_examples}:', end=' ', file=dep)
> + for root, _, files in os.walk(examples_dir):
> + for name in files:
> + is_source = name.endswith('.c')
> + if is_source or name == 'meson.meson.build':
duplicate "meson."
> + path = os.path.join(root, name)
> + if is_source:
> + sources.append(path)
> + print(path , end=' ', file=dep)
> +
> +sys.stdout = open(api_examples, 'w')
While this is a literal translation of what is done in the .sh file, I
wonder if, for consistency, in the python versions we should always either
use stdout redirection or always use "file=" option to printing. Right now
we have a mix of both.
> +print('/**')
> +print('@page examples DPDK Example Programs')
> +print()
Is this additional print done deliberately for clarity vs just putting '\n'
on previous line?
> +for path in sources:
> + # Produce consistent output with forward slashes on all systems.
> + # Every \ in paths within examples directory is a separator, not escape.
> + relpath = os.path.relpath(path, examples_dir).replace('\\', '/')
> + print(f'@example examples/{relpath}')
> +print('*/')
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH 3/3] doc: rewrite shell scripts in Python
2022-04-01 16:31 ` Bruce Richardson
@ 2022-04-01 21:47 ` Dmitry Kozlyuk
0 siblings, 0 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-04-01 21:47 UTC (permalink / raw)
To: Bruce Richardson; +Cc: dev, Vipin Varghese
2022-04-01 17:31 (UTC+0100), Bruce Richardson:
> On Fri, Apr 01, 2022 at 12:28:30AM +0300, Dmitry Kozlyuk wrote:
[...]
> > + if is_source or name == 'meson.meson.build':
>
> duplicate "meson."
Thanks!
> > + path = os.path.join(root, name)
> > + if is_source:
> > + sources.append(path)
> > + print(path , end=' ', file=dep)
> > +
> > +sys.stdout = open(api_examples, 'w')
>
> While this is a literal translation of what is done in the .sh file, I
> wonder if, for consistency, in the python versions we should always either
> use stdout redirection or always use "file=" option to printing. Right now
> we have a mix of both.
I was wondering about this too.
Will change to "file=" (see also below) because explicit is better.
> > +print('/**')
> > +print('@page examples DPDK Example Programs')
> > +print()
>
> Is this additional print done deliberately for clarity vs just putting '\n'
> on previous line?
Yes. I think '''-string will be cleaner, especially with "file=".
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH v2 0/3] doc: build on Windows
2022-03-31 21:28 [PATCH 0/3] doc: build on Windows Dmitry Kozlyuk
` (2 preceding siblings ...)
2022-03-31 21:28 ` [PATCH 3/3] doc: rewrite shell scripts in Python Dmitry Kozlyuk
@ 2022-04-06 17:10 ` Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 1/3] doc: simplify CSS customization for Doxygen Dmitry Kozlyuk
` (4 more replies)
3 siblings, 5 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-04-06 17:10 UTC (permalink / raw)
To: dev; +Cc: Vipin Varghese, Dmitry Kozlyuk
Enable biulding documentation on Windows natively.
Thanks to Vipin for raising the issue.
v2: fix typo in meson.build file name,
use print(file=x) instead of stdout redirection.
Dmitry Kozlyuk (3):
doc: simplify CSS customization for Doxygen
doc: fix API index Markdown syntax
doc: rewrite shell scripts in Python
doc/api/custom.css | 6 +
doc/api/doxy-api-index.md | 366 +++++++++++++++++------------------
doc/api/doxy-api.conf.in | 1 +
doc/api/doxy-html-custom.sh | 8 -
doc/api/generate_doxygen.py | 19 ++
doc/api/generate_doxygen.sh | 15 --
doc/api/generate_examples.py | 31 +++
doc/api/generate_examples.sh | 20 --
doc/api/meson.build | 7 +-
9 files changed, 243 insertions(+), 230 deletions(-)
create mode 100644 doc/api/custom.css
delete mode 100755 doc/api/doxy-html-custom.sh
create mode 100644 doc/api/generate_doxygen.py
delete mode 100755 doc/api/generate_doxygen.sh
create mode 100644 doc/api/generate_examples.py
delete mode 100755 doc/api/generate_examples.sh
--
2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH v2 1/3] doc: simplify CSS customization for Doxygen
2022-04-06 17:10 ` [PATCH v2 0/3] doc: build on Windows Dmitry Kozlyuk
@ 2022-04-06 17:10 ` Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 2/3] doc: fix API index Markdown syntax Dmitry Kozlyuk
` (3 subsequent siblings)
4 siblings, 0 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-04-06 17:10 UTC (permalink / raw)
To: dev; +Cc: Vipin Varghese, Dmitry Kozlyuk
CSS for API documentation was customized by a shell script
modifying the file that Doxygen produces.
This way CSS code is kept in a script and an extra build step is added.
Move custom style to a plain CSS file.
Use Doxygen capability to attach this extra stylesheet.
Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
---
doc/api/custom.css | 6 ++++++
doc/api/doxy-api.conf.in | 1 +
doc/api/doxy-html-custom.sh | 8 --------
doc/api/generate_doxygen.sh | 3 ---
doc/api/meson.build | 3 +--
5 files changed, 8 insertions(+), 13 deletions(-)
create mode 100644 doc/api/custom.css
delete mode 100755 doc/api/doxy-html-custom.sh
diff --git a/doc/api/custom.css b/doc/api/custom.css
new file mode 100644
index 0000000000..66360f9b48
--- /dev/null
+++ b/doc/api/custom.css
@@ -0,0 +1,6 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright 2013 6WIND S.A.
+ */
+
+/* space between item and its comment */
+dd td:first-child { padding-right: 2em; }
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index db2ca9b6ed..8e961cbc8c 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -102,6 +102,7 @@ ALPHABETICAL_INDEX = NO
HTML_TIMESTAMP = NO
HTML_DYNAMIC_SECTIONS = YES
+HTML_EXTRA_STYLESHEET = @TOPDIR@/doc/api/custom.css
SEARCHENGINE = YES
SORT_MEMBER_DOCS = NO
SOURCE_BROWSER = YES
diff --git a/doc/api/doxy-html-custom.sh b/doc/api/doxy-html-custom.sh
deleted file mode 100755
index 3802007c8c..0000000000
--- a/doc/api/doxy-html-custom.sh
+++ /dev/null
@@ -1,8 +0,0 @@
-#! /bin/sh -e
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2013 6WIND S.A.
-
-CSS=$1
-
-# space between item and its comment
-echo 'dd td:first-child {padding-right: 2em;}' >> $CSS
diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
index 1350e50491..1940ea46e2 100755
--- a/doc/api/generate_doxygen.sh
+++ b/doc/api/generate_doxygen.sh
@@ -4,12 +4,9 @@
DOXYCONF=$1
OUTDIR=$2
-SCRIPTCSS=$3
OUT_FILE=$(dirname $OUTDIR)/doxygen.out
# run doxygen, capturing all the header files it processed
doxygen "${DOXYCONF}" > $OUT_FILE
echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' $OUT_FILE)" > $OUTDIR.d
-
-"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
diff --git a/doc/api/meson.build b/doc/api/meson.build
index 5c25b92092..53338a02d6 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -13,7 +13,6 @@ endif
# 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')
htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')
@@ -52,7 +51,7 @@ doxy_build = custom_target('doxygen',
input: doxy_conf,
output: 'html',
depfile: 'html.d',
- command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
+ command: [generate_doxygen, '@INPUT@', '@OUTPUT@'],
install: get_option('enable_docs'),
install_dir: htmldir,
build_by_default: get_option('enable_docs'))
--
2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH v2 2/3] doc: fix API index Markdown syntax
2022-04-06 17:10 ` [PATCH v2 0/3] doc: build on Windows Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 1/3] doc: simplify CSS customization for Doxygen Dmitry Kozlyuk
@ 2022-04-06 17:10 ` Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 3/3] doc: rewrite shell scripts in Python Dmitry Kozlyuk
` (2 subsequent siblings)
4 siblings, 0 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-04-06 17:10 UTC (permalink / raw)
To: dev
Cc: Vipin Varghese, Dmitry Kozlyuk, Thomas Monjalon, Olivier Matz,
David Marchand
API documentation index had spaces between link caption and URL,
which may be unsupported by some Markdown implementations.
That is, "[caption](URL)" is valid but "[caption] (URL)" is not.
The problematic behavior is observed with Doxygen on Windows.
Remove the spaces.
Unfortunately, Markdown syntax is not formally specified.
Fixes: 9bf486e606b0 ("doc: generate HTML for API with doxygen")
Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
---
doc/api/doxy-api-index.md | 366 +++++++++++++++++++-------------------
1 file changed, 183 insertions(+), 183 deletions(-)
diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index 4245b9635c..baecb2e52e 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -9,222 +9,222 @@ API
The public API headers are grouped by topics:
- **device**:
- [dev] (@ref rte_dev.h),
- [ethdev] (@ref rte_ethdev.h),
- [ethctrl] (@ref rte_eth_ctrl.h),
- [rte_flow] (@ref rte_flow.h),
- [rte_tm] (@ref rte_tm.h),
- [rte_mtr] (@ref rte_mtr.h),
- [bbdev] (@ref rte_bbdev.h),
- [cryptodev] (@ref rte_cryptodev.h),
- [security] (@ref rte_security.h),
- [compressdev] (@ref rte_compressdev.h),
- [compress] (@ref rte_comp.h),
- [regexdev] (@ref rte_regexdev.h),
- [dmadev] (@ref rte_dmadev.h),
- [eventdev] (@ref rte_eventdev.h),
- [event_eth_rx_adapter] (@ref rte_event_eth_rx_adapter.h),
- [event_eth_tx_adapter] (@ref rte_event_eth_tx_adapter.h),
- [event_timer_adapter] (@ref rte_event_timer_adapter.h),
- [event_crypto_adapter] (@ref rte_event_crypto_adapter.h),
- [rawdev] (@ref rte_rawdev.h),
- [metrics] (@ref rte_metrics.h),
- [bitrate] (@ref rte_bitrate.h),
- [latency] (@ref rte_latencystats.h),
- [devargs] (@ref rte_devargs.h),
- [PCI] (@ref rte_pci.h),
- [vdev] (@ref rte_bus_vdev.h),
- [vfio] (@ref rte_vfio.h)
+ [dev](@ref rte_dev.h),
+ [ethdev](@ref rte_ethdev.h),
+ [ethctrl](@ref rte_eth_ctrl.h),
+ [rte_flow](@ref rte_flow.h),
+ [rte_tm](@ref rte_tm.h),
+ [rte_mtr](@ref rte_mtr.h),
+ [bbdev](@ref rte_bbdev.h),
+ [cryptodev](@ref rte_cryptodev.h),
+ [security](@ref rte_security.h),
+ [compressdev](@ref rte_compressdev.h),
+ [compress](@ref rte_comp.h),
+ [regexdev](@ref rte_regexdev.h),
+ [dmadev](@ref rte_dmadev.h),
+ [eventdev](@ref rte_eventdev.h),
+ [event_eth_rx_adapter](@ref rte_event_eth_rx_adapter.h),
+ [event_eth_tx_adapter](@ref rte_event_eth_tx_adapter.h),
+ [event_timer_adapter](@ref rte_event_timer_adapter.h),
+ [event_crypto_adapter](@ref rte_event_crypto_adapter.h),
+ [rawdev](@ref rte_rawdev.h),
+ [metrics](@ref rte_metrics.h),
+ [bitrate](@ref rte_bitrate.h),
+ [latency](@ref rte_latencystats.h),
+ [devargs](@ref rte_devargs.h),
+ [PCI](@ref rte_pci.h),
+ [vdev](@ref rte_bus_vdev.h),
+ [vfio](@ref rte_vfio.h)
- **device specific**:
- [softnic] (@ref rte_eth_softnic.h),
- [bond] (@ref rte_eth_bond.h),
- [vhost] (@ref rte_vhost.h),
- [vdpa] (@ref rte_vdpa.h),
- [KNI] (@ref rte_kni.h),
- [ixgbe] (@ref rte_pmd_ixgbe.h),
- [i40e] (@ref rte_pmd_i40e.h),
- [ice] (@ref rte_pmd_ice.h),
- [iavf] (@ref rte_pmd_iavf.h),
- [ioat] (@ref rte_ioat_rawdev.h),
- [bnxt] (@ref rte_pmd_bnxt.h),
- [dpaa] (@ref rte_pmd_dpaa.h),
- [dpaa2] (@ref rte_pmd_dpaa2.h),
- [mlx5] (@ref rte_pmd_mlx5.h),
- [dpaa2_mempool] (@ref rte_dpaa2_mempool.h),
- [dpaa2_cmdif] (@ref rte_pmd_dpaa2_cmdif.h),
- [dpaa2_qdma] (@ref rte_pmd_dpaa2_qdma.h),
- [crypto_scheduler] (@ref rte_cryptodev_scheduler.h),
- [dlb2] (@ref rte_pmd_dlb2.h),
- [ifpga] (@ref rte_pmd_ifpga.h)
+ [softnic](@ref rte_eth_softnic.h),
+ [bond](@ref rte_eth_bond.h),
+ [vhost](@ref rte_vhost.h),
+ [vdpa](@ref rte_vdpa.h),
+ [KNI](@ref rte_kni.h),
+ [ixgbe](@ref rte_pmd_ixgbe.h),
+ [i40e](@ref rte_pmd_i40e.h),
+ [ice](@ref rte_pmd_ice.h),
+ [iavf](@ref rte_pmd_iavf.h),
+ [ioat](@ref rte_ioat_rawdev.h),
+ [bnxt](@ref rte_pmd_bnxt.h),
+ [dpaa](@ref rte_pmd_dpaa.h),
+ [dpaa2](@ref rte_pmd_dpaa2.h),
+ [mlx5](@ref rte_pmd_mlx5.h),
+ [dpaa2_mempool](@ref rte_dpaa2_mempool.h),
+ [dpaa2_cmdif](@ref rte_pmd_dpaa2_cmdif.h),
+ [dpaa2_qdma](@ref rte_pmd_dpaa2_qdma.h),
+ [crypto_scheduler](@ref rte_cryptodev_scheduler.h),
+ [dlb2](@ref rte_pmd_dlb2.h),
+ [ifpga](@ref rte_pmd_ifpga.h)
- **memory**:
- [memseg] (@ref rte_memory.h),
- [memzone] (@ref rte_memzone.h),
- [mempool] (@ref rte_mempool.h),
- [malloc] (@ref rte_malloc.h),
- [memcpy] (@ref rte_memcpy.h)
+ [memseg](@ref rte_memory.h),
+ [memzone](@ref rte_memzone.h),
+ [mempool](@ref rte_mempool.h),
+ [malloc](@ref rte_malloc.h),
+ [memcpy](@ref rte_memcpy.h)
- **timers**:
- [cycles] (@ref rte_cycles.h),
- [timer] (@ref rte_timer.h),
- [alarm] (@ref rte_alarm.h)
+ [cycles](@ref rte_cycles.h),
+ [timer](@ref rte_timer.h),
+ [alarm](@ref rte_alarm.h)
- **locks**:
- [atomic] (@ref rte_atomic.h),
- [mcslock] (@ref rte_mcslock.h),
- [pflock] (@ref rte_pflock.h),
- [rwlock] (@ref rte_rwlock.h),
- [spinlock] (@ref rte_spinlock.h),
- [ticketlock] (@ref rte_ticketlock.h),
- [RCU] (@ref rte_rcu_qsbr.h)
+ [atomic](@ref rte_atomic.h),
+ [mcslock](@ref rte_mcslock.h),
+ [pflock](@ref rte_pflock.h),
+ [rwlock](@ref rte_rwlock.h),
+ [spinlock](@ref rte_spinlock.h),
+ [ticketlock](@ref rte_ticketlock.h),
+ [RCU](@ref rte_rcu_qsbr.h)
- **CPU arch**:
- [branch prediction] (@ref rte_branch_prediction.h),
- [cache prefetch] (@ref rte_prefetch.h),
- [SIMD] (@ref rte_vect.h),
- [byte order] (@ref rte_byteorder.h),
- [CPU flags] (@ref rte_cpuflags.h),
- [CPU pause] (@ref rte_pause.h),
- [I/O access] (@ref rte_io.h),
- [power management] (@ref rte_power_intrinsics.h)
+ [branch prediction](@ref rte_branch_prediction.h),
+ [cache prefetch](@ref rte_prefetch.h),
+ [SIMD](@ref rte_vect.h),
+ [byte order](@ref rte_byteorder.h),
+ [CPU flags](@ref rte_cpuflags.h),
+ [CPU pause](@ref rte_pause.h),
+ [I/O access](@ref rte_io.h),
+ [power management](@ref rte_power_intrinsics.h)
- **CPU multicore**:
- [interrupts] (@ref rte_interrupts.h),
- [launch] (@ref rte_launch.h),
- [lcore] (@ref rte_lcore.h),
- [per-lcore] (@ref rte_per_lcore.h),
- [service cores] (@ref rte_service.h),
- [keepalive] (@ref rte_keepalive.h),
- [power/freq] (@ref rte_power.h),
- [PMD power] (@ref rte_power_pmd_mgmt.h)
+ [interrupts](@ref rte_interrupts.h),
+ [launch](@ref rte_launch.h),
+ [lcore](@ref rte_lcore.h),
+ [per-lcore](@ref rte_per_lcore.h),
+ [service cores](@ref rte_service.h),
+ [keepalive](@ref rte_keepalive.h),
+ [power/freq](@ref rte_power.h),
+ [PMD power](@ref rte_power_pmd_mgmt.h)
- **layers**:
- [ethernet] (@ref rte_ether.h),
- [ARP] (@ref rte_arp.h),
- [HIGIG] (@ref rte_higig.h),
- [ICMP] (@ref rte_icmp.h),
- [ESP] (@ref rte_esp.h),
- [IPsec] (@ref rte_ipsec.h),
- [IPsec group] (@ref rte_ipsec_group.h),
- [IPsec SA] (@ref rte_ipsec_sa.h),
- [IPsec SAD] (@ref rte_ipsec_sad.h),
- [IP] (@ref rte_ip.h),
- [frag/reass] (@ref rte_ip_frag.h),
- [SCTP] (@ref rte_sctp.h),
- [TCP] (@ref rte_tcp.h),
- [UDP] (@ref rte_udp.h),
- [GTP] (@ref rte_gtp.h),
- [GRO] (@ref rte_gro.h),
- [GSO] (@ref rte_gso.h),
- [GRE] (@ref rte_gre.h),
- [MPLS] (@ref rte_mpls.h),
- [VXLAN] (@ref rte_vxlan.h),
- [Geneve] (@ref rte_geneve.h),
- [eCPRI] (@ref rte_ecpri.h),
- [L2TPv2] (@ref rte_l2tpv2.h),
- [PPP] (@ref rte_ppp.h)
+ [ethernet](@ref rte_ether.h),
+ [ARP](@ref rte_arp.h),
+ [HIGIG](@ref rte_higig.h),
+ [ICMP](@ref rte_icmp.h),
+ [ESP](@ref rte_esp.h),
+ [IPsec](@ref rte_ipsec.h),
+ [IPsec group](@ref rte_ipsec_group.h),
+ [IPsec SA](@ref rte_ipsec_sa.h),
+ [IPsec SAD](@ref rte_ipsec_sad.h),
+ [IP](@ref rte_ip.h),
+ [frag/reass](@ref rte_ip_frag.h),
+ [SCTP](@ref rte_sctp.h),
+ [TCP](@ref rte_tcp.h),
+ [UDP](@ref rte_udp.h),
+ [GTP](@ref rte_gtp.h),
+ [GRO](@ref rte_gro.h),
+ [GSO](@ref rte_gso.h),
+ [GRE](@ref rte_gre.h),
+ [MPLS](@ref rte_mpls.h),
+ [VXLAN](@ref rte_vxlan.h),
+ [Geneve](@ref rte_geneve.h),
+ [eCPRI](@ref rte_ecpri.h),
+ [L2TPv2](@ref rte_l2tpv2.h),
+ [PPP](@ref rte_ppp.h)
- **QoS**:
- [metering] (@ref rte_meter.h),
- [scheduler] (@ref rte_sched.h),
- [RED congestion] (@ref rte_red.h)
+ [metering](@ref rte_meter.h),
+ [scheduler](@ref rte_sched.h),
+ [RED congestion](@ref rte_red.h)
- **routing**:
- [LPM IPv4 route] (@ref rte_lpm.h),
- [LPM IPv6 route] (@ref rte_lpm6.h),
- [RIB IPv4] (@ref rte_rib.h),
- [RIB IPv6] (@ref rte_rib6.h),
- [FIB IPv4] (@ref rte_fib.h),
- [FIB IPv6] (@ref rte_fib6.h)
+ [LPM IPv4 route](@ref rte_lpm.h),
+ [LPM IPv6 route](@ref rte_lpm6.h),
+ [RIB IPv4](@ref rte_rib.h),
+ [RIB IPv6](@ref rte_rib6.h),
+ [FIB IPv4](@ref rte_fib.h),
+ [FIB IPv6](@ref rte_fib6.h)
- **hashes**:
- [hash] (@ref rte_hash.h),
- [jhash] (@ref rte_jhash.h),
- [thash] (@ref rte_thash.h),
- [thash_gfni] (@ref rte_thash_gfni.h),
- [FBK hash] (@ref rte_fbk_hash.h),
- [CRC hash] (@ref rte_hash_crc.h)
+ [hash](@ref rte_hash.h),
+ [jhash](@ref rte_jhash.h),
+ [thash](@ref rte_thash.h),
+ [thash_gfni](@ref rte_thash_gfni.h),
+ [FBK hash](@ref rte_fbk_hash.h),
+ [CRC hash](@ref rte_hash_crc.h)
- **classification**
- [reorder] (@ref rte_reorder.h),
- [distributor] (@ref rte_distributor.h),
- [EFD] (@ref rte_efd.h),
- [ACL] (@ref rte_acl.h),
- [member] (@ref rte_member.h),
- [flow classify] (@ref rte_flow_classify.h),
- [BPF] (@ref rte_bpf.h)
+ [reorder](@ref rte_reorder.h),
+ [distributor](@ref rte_distributor.h),
+ [EFD](@ref rte_efd.h),
+ [ACL](@ref rte_acl.h),
+ [member](@ref rte_member.h),
+ [flow classify](@ref rte_flow_classify.h),
+ [BPF](@ref rte_bpf.h)
- **containers**:
- [mbuf] (@ref rte_mbuf.h),
- [mbuf pool ops] (@ref rte_mbuf_pool_ops.h),
- [ring] (@ref rte_ring.h),
- [stack] (@ref rte_stack.h),
- [tailq] (@ref rte_tailq.h),
- [bitmap] (@ref rte_bitmap.h)
+ [mbuf](@ref rte_mbuf.h),
+ [mbuf pool ops](@ref rte_mbuf_pool_ops.h),
+ [ring](@ref rte_ring.h),
+ [stack](@ref rte_stack.h),
+ [tailq](@ref rte_tailq.h),
+ [bitmap](@ref rte_bitmap.h)
- **packet framework**:
- * [port] (@ref rte_port.h):
- [ethdev] (@ref rte_port_ethdev.h),
- [ring] (@ref rte_port_ring.h),
- [frag] (@ref rte_port_frag.h),
- [reass] (@ref rte_port_ras.h),
- [sched] (@ref rte_port_sched.h),
- [kni] (@ref rte_port_kni.h),
- [src/sink] (@ref rte_port_source_sink.h)
- * [table] (@ref rte_table.h):
- [lpm IPv4] (@ref rte_table_lpm.h),
- [lpm IPv6] (@ref rte_table_lpm_ipv6.h),
- [ACL] (@ref rte_table_acl.h),
- [hash] (@ref rte_table_hash.h),
- [array] (@ref rte_table_array.h),
- [stub] (@ref rte_table_stub.h)
- * [pipeline] (@ref rte_pipeline.h)
- [port_in_action] (@ref rte_port_in_action.h)
- [table_action] (@ref rte_table_action.h)
+ * [port](@ref rte_port.h):
+ [ethdev](@ref rte_port_ethdev.h),
+ [ring](@ref rte_port_ring.h),
+ [frag](@ref rte_port_frag.h),
+ [reass](@ref rte_port_ras.h),
+ [sched](@ref rte_port_sched.h),
+ [kni](@ref rte_port_kni.h),
+ [src/sink](@ref rte_port_source_sink.h)
+ * [table](@ref rte_table.h):
+ [lpm IPv4](@ref rte_table_lpm.h),
+ [lpm IPv6](@ref rte_table_lpm_ipv6.h),
+ [ACL](@ref rte_table_acl.h),
+ [hash](@ref rte_table_hash.h),
+ [array](@ref rte_table_array.h),
+ [stub](@ref rte_table_stub.h)
+ * [pipeline](@ref rte_pipeline.h)
+ [port_in_action](@ref rte_port_in_action.h)
+ [table_action](@ref rte_table_action.h)
* SWX pipeline:
- [control] (@ref rte_swx_ctl.h),
- [extern] (@ref rte_swx_extern.h),
- [pipeline] (@ref rte_swx_pipeline.h)
+ [control](@ref rte_swx_ctl.h),
+ [extern](@ref rte_swx_extern.h),
+ [pipeline](@ref rte_swx_pipeline.h)
* SWX port:
- [port] (@ref rte_swx_port.h),
- [ethdev] (@ref rte_swx_port_ethdev.h),
- [fd] (@ref rte_swx_port_fd.h),
- [ring] (@ref rte_swx_port_ring.h),
- [src/sink] (@ref rte_swx_port_source_sink.h)
+ [port](@ref rte_swx_port.h),
+ [ethdev](@ref rte_swx_port_ethdev.h),
+ [fd](@ref rte_swx_port_fd.h),
+ [ring](@ref rte_swx_port_ring.h),
+ [src/sink](@ref rte_swx_port_source_sink.h)
* SWX table:
- [table] (@ref rte_swx_table.h),
- [table_em] (@ref rte_swx_table_em.h)
- [table_wm] (@ref rte_swx_table_wm.h)
- * [graph] (@ref rte_graph.h):
- [graph_worker] (@ref rte_graph_worker.h)
+ [table](@ref rte_swx_table.h),
+ [table_em](@ref rte_swx_table_em.h)
+ [table_wm](@ref rte_swx_table_wm.h)
+ * [graph](@ref rte_graph.h):
+ [graph_worker](@ref rte_graph_worker.h)
* graph_nodes:
- [eth_node] (@ref rte_node_eth_api.h),
- [ip4_node] (@ref rte_node_ip4_api.h)
+ [eth_node](@ref rte_node_eth_api.h),
+ [ip4_node](@ref rte_node_ip4_api.h)
- **basic**:
- [bitops] (@ref rte_bitops.h),
- [approx fraction] (@ref rte_approx.h),
- [random] (@ref rte_random.h),
- [config file] (@ref rte_cfgfile.h),
- [key/value args] (@ref rte_kvargs.h),
- [string] (@ref rte_string_fns.h)
+ [bitops](@ref rte_bitops.h),
+ [approx fraction](@ref rte_approx.h),
+ [random](@ref rte_random.h),
+ [config file](@ref rte_cfgfile.h),
+ [key/value args](@ref rte_kvargs.h),
+ [string](@ref rte_string_fns.h)
- **debug**:
- [jobstats] (@ref rte_jobstats.h),
- [telemetry] (@ref rte_telemetry.h),
- [pcapng] (@ref rte_pcapng.h),
- [pdump] (@ref rte_pdump.h),
- [hexdump] (@ref rte_hexdump.h),
- [debug] (@ref rte_debug.h),
- [log] (@ref rte_log.h),
- [errno] (@ref rte_errno.h),
- [trace] (@ref rte_trace.h),
- [trace_point] (@ref rte_trace_point.h)
+ [jobstats](@ref rte_jobstats.h),
+ [telemetry](@ref rte_telemetry.h),
+ [pcapng](@ref rte_pcapng.h),
+ [pdump](@ref rte_pdump.h),
+ [hexdump](@ref rte_hexdump.h),
+ [debug](@ref rte_debug.h),
+ [log](@ref rte_log.h),
+ [errno](@ref rte_errno.h),
+ [trace](@ref rte_trace.h),
+ [trace_point](@ref rte_trace_point.h)
- **misc**:
- [EAL config] (@ref rte_eal.h),
- [common] (@ref rte_common.h),
- [experimental APIs] (@ref rte_compat.h),
- [ABI versioning] (@ref rte_function_versioning.h),
- [version] (@ref rte_version.h)
+ [EAL config](@ref rte_eal.h),
+ [common](@ref rte_common.h),
+ [experimental APIs](@ref rte_compat.h),
+ [ABI versioning](@ref rte_function_versioning.h),
+ [version](@ref rte_version.h)
--
2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH v2 3/3] doc: rewrite shell scripts in Python
2022-04-06 17:10 ` [PATCH v2 0/3] doc: build on Windows Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 1/3] doc: simplify CSS customization for Doxygen Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 2/3] doc: fix API index Markdown syntax Dmitry Kozlyuk
@ 2022-04-06 17:10 ` Dmitry Kozlyuk
2022-05-11 9:34 ` [PATCH v2 0/3] doc: build on Windows Varghese, Vipin
2022-06-01 10:47 ` Thomas Monjalon
4 siblings, 0 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-04-06 17:10 UTC (permalink / raw)
To: dev; +Cc: Vipin Varghese, Dmitry Kozlyuk, Bruce Richardson
Shell used in documentation generation could not run on Windows.
Rewrite scripts in Python.
New scripts use proper path separators and handle paths with spaces.
Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
Reviewed-by: Bruce Richardson <bruce.richardson@intel.com>
---
doc/api/generate_doxygen.py | 19 +++++++++++++++++++
doc/api/generate_doxygen.sh | 12 ------------
doc/api/generate_examples.py | 31 +++++++++++++++++++++++++++++++
doc/api/generate_examples.sh | 20 --------------------
doc/api/meson.build | 6 +++---
5 files changed, 53 insertions(+), 35 deletions(-)
create mode 100644 doc/api/generate_doxygen.py
delete mode 100755 doc/api/generate_doxygen.sh
create mode 100644 doc/api/generate_examples.py
delete mode 100755 doc/api/generate_examples.sh
diff --git a/doc/api/generate_doxygen.py b/doc/api/generate_doxygen.py
new file mode 100644
index 0000000000..2ccedf844e
--- /dev/null
+++ b/doc/api/generate_doxygen.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# (c) 2018 Luca Boccassi <bluca@debian.org>
+# (c) 2022 Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
+
+import os, re, subprocess, sys
+
+pattern = re.compile('^Preprocessing (.*)...$')
+out_dir, *doxygen_command = sys.argv[1:]
+out_file = os.path.join(os.path.dirname(out_dir), 'doxygen.out')
+dep_file = f'{out_dir}.d'
+with open(out_file, 'w') as out:
+ subprocess.run(doxygen_command, check=True, stdout=out)
+with open(out_file) as out, open(dep_file, 'w') as dep:
+ print(f'{out_dir}:', end=' ', file=dep)
+ for line in out:
+ match = re.match(pattern, line)
+ if match:
+ print(match.group(1), end=' ', file=dep)
diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
deleted file mode 100755
index 1940ea46e2..0000000000
--- a/doc/api/generate_doxygen.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#! /bin/sh -e
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2018 Luca Boccassi <bluca@debian.org>
-
-DOXYCONF=$1
-OUTDIR=$2
-
-OUT_FILE=$(dirname $OUTDIR)/doxygen.out
-
-# run doxygen, capturing all the header files it processed
-doxygen "${DOXYCONF}" > $OUT_FILE
-echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' $OUT_FILE)" > $OUTDIR.d
diff --git a/doc/api/generate_examples.py b/doc/api/generate_examples.py
new file mode 100644
index 0000000000..c35e72f280
--- /dev/null
+++ b/doc/api/generate_examples.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# (c) 2018 Luca Boccassi <bluca@debian.org>
+# (c) 2022 Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
+
+import os, sys
+
+examples_dir, api_examples = sys.argv[1:]
+
+sources = []
+with open(f'{api_examples}.d', 'w') as dep:
+ print(f'{api_examples}:', end=' ', file=dep)
+ for root, _, files in os.walk(examples_dir):
+ for name in files:
+ is_source = name.endswith('.c')
+ if is_source or name == 'meson.build':
+ path = os.path.join(root, name)
+ if is_source:
+ sources.append(path)
+ print(path , end=' ', file=dep)
+
+with open(api_examples, 'w') as out:
+ print('''/**
+@page examples DPDK Example Programs
+''', file=out)
+ for path in sources:
+ # Produce consistent output with forward slashes on all systems.
+ # Every \ in paths within examples directory is a separator, not escape.
+ relpath = os.path.relpath(path, examples_dir).replace('\\', '/')
+ print(f'@example examples/{relpath}', file=out)
+ print('*/', file=out)
diff --git a/doc/api/generate_examples.sh b/doc/api/generate_examples.sh
deleted file mode 100755
index 48574563ca..0000000000
--- a/doc/api/generate_examples.sh
+++ /dev/null
@@ -1,20 +0,0 @@
-#! /bin/sh -e
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2018 Luca Boccassi <bluca@debian.org>
-
-EXAMPLES_DIR=$1
-API_EXAMPLES=$2
-
-FIND=find
-
-# generate a .d file including both C files and also build files, so we can
-# detect both file changes and file additions/deletions
-echo "$API_EXAMPLES: $($FIND ${EXAMPLES_DIR} -type f \( -name '*.c' -o -name 'meson.build' \) | tr '\n' ' ' )" > ${API_EXAMPLES}.d
-
-exec > "${API_EXAMPLES}"
-printf '/**\n'
-printf '@page examples DPDK Example Programs\n\n'
-$FIND "${EXAMPLES_DIR}" -type f -name '*.c' |
- sed "s|${EXAMPLES_DIR}|@example examples|" |
- LC_ALL=C sort
-printf '*/\n'
diff --git a/doc/api/meson.build b/doc/api/meson.build
index 53338a02d6..2876a78a7e 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -11,8 +11,8 @@ endif
# 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_doxygen = py3 + files('generate_doxygen.py')
+generate_examples = py3 + files('generate_examples.py')
htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')
@@ -51,7 +51,7 @@ doxy_build = custom_target('doxygen',
input: doxy_conf,
output: 'html',
depfile: 'html.d',
- command: [generate_doxygen, '@INPUT@', '@OUTPUT@'],
+ command: [generate_doxygen, '@OUTPUT@', doxygen, '@INPUT@'],
install: get_option('enable_docs'),
install_dir: htmldir,
build_by_default: get_option('enable_docs'))
--
2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: [PATCH v2 0/3] doc: build on Windows
2022-04-06 17:10 ` [PATCH v2 0/3] doc: build on Windows Dmitry Kozlyuk
` (2 preceding siblings ...)
2022-04-06 17:10 ` [PATCH v2 3/3] doc: rewrite shell scripts in Python Dmitry Kozlyuk
@ 2022-05-11 9:34 ` Varghese, Vipin
2022-05-11 10:56 ` Dmitry Kozlyuk
2022-06-01 10:47 ` Thomas Monjalon
4 siblings, 1 reply; 13+ messages in thread
From: Varghese, Vipin @ 2022-05-11 9:34 UTC (permalink / raw)
To: Dmitry Kozlyuk, dev
[AMD Official Use Only - General]
Hi Dmitry,
Thank you for allowing me to try these changes on both Linux & Windows. I was facing some hurdles in both environments.
On Linux I was facing
```
Traceback (most recent call last):
File "/home/amd/vipin/dpdk/test/dpdk/doc/api/generate_doxygen.py", line 13, in <module>
subprocess.run(doxygen_command, check=True, stdout=out)
File "/usr/lib/python3.8/subprocess.py", line 493, in run
with Popen(*popenargs, **kwargs) as process:
File "/usr/lib/python3.8/subprocess.py", line 858, in __init__
self._execute_child(args, executable, preexec_fn, close_fds,
File "/usr/lib/python3.8/subprocess.py", line 1580, in _execute_child
executable = args[0]
IndexError: list index out of range
```
With some debugging this was root caused to `doxygen permission issue in the environment`. Re-running the `ninja -C build` with root user solved this for me.
For Windows I faced
```
[528/682] Generating doc/guides/html_guides with a custom command
FAILED: doc/guides/html
"C:\Program Files\Meson\meson.exe" "runpython" "../buildtools/call-sphinx-build.py" "C:/Users/Administrator/AppData/Local/Programs/Python/Python310/Scripts/sphinx-build.EXE" "22.07.0-rc0" "C:/Users/Administrator/Desktop/docs/doc/guides" "C:/Users/Administrator/Desktop/docs/build/doc/guides"
Traceback (most recent call last):
File "mesonbuild\mesonmain.py", line 146, in run
File "mesonbuild\mesonmain.py", line 106, in run_runpython_command
File "runpy.py", line 269, in run_path
File "runpy.py", line 96, in _run_module_code
File "runpy.py", line 86, in _run_code
File "../buildtools/call-sphinx-build.py", line 10, in <module>
from packaging.version import Version
ModuleNotFoundError: No module named 'packaging'
ERROR: Unhandled python exception
```
Checking for `packaging` in windows, the library is present
```
C:\Users\Administrator\Desktop\docs>pip3 install packaging
Requirement already satisfied: packaging in c:\users\administrator\appdata\local\programs\python\python310\lib\site-packages (21.3)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in c:\users\administrator\appdata\local\programs\python\python310\lib\site-packages (from packaging) (3.0.7)
```
Running python directly gives success for package as
```
import packaging
dir(packaging)
['__about__', '__all__', '__author__', '__builtins__', '__cached__', '__copyright__', '__doc__', '__email__', '__file__', '__license__', '__loader__', '__name__', '__package__', '__path__', '__spec__', '__summary__', '__title__', '__uri__', '__version__']
```
So the problem is narrowed down `sys.path` variation as
```
Path from standalone run for call-sphinx-build.py: ['C:\\Users\\Administrator\\Desktop\\docs\\buildtools', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\python310.zip', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\DLLs', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\lib', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\lib\\site-packages']
Path from ninja build for docs for call-sphinx-build.py: ['../buildtools', 'C:\\Program Files\\Meson\\base_library.zip', 'C:\\Program Files\\Meson\\lib-dynload', 'C:\\Program Files\\Meson']
```
> -----Original Message-----
> From: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
> Sent: Wednesday, April 6, 2022 10:40 PM
> To: dev@dpdk.org
> Cc: Varghese, Vipin <Vipin.Varghese@amd.com>; Dmitry Kozlyuk
> <dmitry.kozliuk@gmail.com>
> Subject: [PATCH v2 0/3] doc: build on Windows
>
> [CAUTION: External Email]
>
> Enable biulding documentation on Windows natively.
> Thanks to Vipin for raising the issue.
>
> v2: fix typo in meson.build file name,
> use print(file=x) instead of stdout redirection.
>
> Dmitry Kozlyuk (3):
> doc: simplify CSS customization for Doxygen
> doc: fix API index Markdown syntax
> doc: rewrite shell scripts in Python
>
> doc/api/custom.css | 6 +
> doc/api/doxy-api-index.md | 366 +++++++++++++++++------------------
> doc/api/doxy-api.conf.in | 1 +
> doc/api/doxy-html-custom.sh | 8 -
> doc/api/generate_doxygen.py | 19 ++
> doc/api/generate_doxygen.sh | 15 --
> doc/api/generate_examples.py | 31 +++
> doc/api/generate_examples.sh | 20 --
> doc/api/meson.build | 7 +-
> 9 files changed, 243 insertions(+), 230 deletions(-) create mode 100644
> doc/api/custom.css delete mode 100755 doc/api/doxy-html-custom.sh create
> mode 100644 doc/api/generate_doxygen.py delete mode 100755
> doc/api/generate_doxygen.sh create mode 100644
> doc/api/generate_examples.py delete mode 100755
> doc/api/generate_examples.sh
>
> --
> 2.29.3
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH v2 0/3] doc: build on Windows
2022-05-11 9:34 ` [PATCH v2 0/3] doc: build on Windows Varghese, Vipin
@ 2022-05-11 10:56 ` Dmitry Kozlyuk
0 siblings, 0 replies; 13+ messages in thread
From: Dmitry Kozlyuk @ 2022-05-11 10:56 UTC (permalink / raw)
To: Varghese, Vipin; +Cc: dev, Bruce Richardson
Hi Vipin,
2022-05-11 09:34 (UTC+0000), Varghese, Vipin:
> For Windows I faced
>
> ```
> [528/682] Generating doc/guides/html_guides with a custom command
> FAILED: doc/guides/html
> "C:\Program Files\Meson\meson.exe" "runpython" "../buildtools/call-sphinx-build.py" "C:/Users/Administrator/AppData/Local/Programs/Python/Python310/Scripts/sphinx-build.EXE" "22.07.0-rc0" "C:/Users/Administrator/Desktop/docs/doc/guides" "C:/Users/Administrator/Desktop/docs/build/doc/guides"
> Traceback (most recent call last):
> File "mesonbuild\mesonmain.py", line 146, in run
> File "mesonbuild\mesonmain.py", line 106, in run_runpython_command
> File "runpy.py", line 269, in run_path
> File "runpy.py", line 96, in _run_module_code
> File "runpy.py", line 86, in _run_code
> File "../buildtools/call-sphinx-build.py", line 10, in <module>
> from packaging.version import Version
> ModuleNotFoundError: No module named 'packaging'
>
> ERROR: Unhandled python exception
> ```
[...]
> So the problem is narrowed down `sys.path` variation as
>
> ```
> Path from standalone run for call-sphinx-build.py: ['C:\\Users\\Administrator\\Desktop\\docs\\buildtools', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\python310.zip', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\DLLs', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\lib', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310', 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python310\\lib\\site-packages']
>
> Path from ninja build for docs for call-sphinx-build.py: ['../buildtools', 'C:\\Program Files\\Meson\\base_library.zip', 'C:\\Program Files\\Meson\\lib-dynload', 'C:\\Program Files\\Meson']
> ```
Thanks for testing.
The Linux issue seems to be exclusively related to you environment.
For the Windows issue: I have both Meson and Sphinx installed via pip3,
your setup seems to have Meson installed separately and using its own Python.
Bruce, can you advise if Python tools are supposed to work
when Meson's Python is different from the system Python?
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH v2 0/3] doc: build on Windows
2022-04-06 17:10 ` [PATCH v2 0/3] doc: build on Windows Dmitry Kozlyuk
` (3 preceding siblings ...)
2022-05-11 9:34 ` [PATCH v2 0/3] doc: build on Windows Varghese, Vipin
@ 2022-06-01 10:47 ` Thomas Monjalon
4 siblings, 0 replies; 13+ messages in thread
From: Thomas Monjalon @ 2022-06-01 10:47 UTC (permalink / raw)
To: Dmitry Kozlyuk; +Cc: dev, Vipin Varghese, bruce.richardson
> Dmitry Kozlyuk (3):
> doc: simplify CSS customization for Doxygen
> doc: fix API index Markdown syntax
> doc: rewrite shell scripts in Python
Applied, thanks.
I hope the Windows setup issue seen by Vipin can be workarounded.
^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2022-06-01 10:47 UTC | newest]
Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-03-31 21:28 [PATCH 0/3] doc: build on Windows Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 1/3] doc: simplify CSS customization for Doxygen Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 2/3] doc: fix API index Markdown syntax Dmitry Kozlyuk
2022-03-31 21:28 ` [PATCH 3/3] doc: rewrite shell scripts in Python Dmitry Kozlyuk
2022-04-01 16:31 ` Bruce Richardson
2022-04-01 21:47 ` Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 0/3] doc: build on Windows Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 1/3] doc: simplify CSS customization for Doxygen Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 2/3] doc: fix API index Markdown syntax Dmitry Kozlyuk
2022-04-06 17:10 ` [PATCH v2 3/3] doc: rewrite shell scripts in Python Dmitry Kozlyuk
2022-05-11 9:34 ` [PATCH v2 0/3] doc: build on Windows Varghese, Vipin
2022-05-11 10:56 ` Dmitry Kozlyuk
2022-06-01 10:47 ` Thomas Monjalon
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).