[dpdk-dev,v2] doc: automate examples file list for API doc
Checks
Commit Message
These files are linked to API documentation as usage samples, list of
files created automatically during doc creation.
Remove manually updated old one.
Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
---
doc/api/doxy-api.conf | 1 -
doc/api/examples.dox | 115 --------------------------------------------------
mk/rte.sdkdoc.mk | 14 +++++-
3 files changed, 13 insertions(+), 117 deletions(-)
delete mode 100644 doc/api/examples.dox
Comments
2017-01-27 17:37, Ferruh Yigit:
> These files are linked to API documentation as usage samples, list of
> files created automatically during doc creation.
>
> Remove manually updated old one.
>
> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
[...]
> +API_EXAMPLES := $(RTE_OUTPUT)/doc/html/examples.dox
I feel it should be in $(RTE_OUTPUT)/doc/ because the doc could be generated
in another format (not HTML only).
[...]
> @echo 'doxygen for API...'
> $(Q)mkdir -p $(RTE_OUTPUT)/doc/html
> $(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf && \
> + echo INPUT += $(API_EXAMPLES) && \
> printf 'PROJECT_NUMBER = ' && \
> $(MAKE) -rR showversion && \
It would be nicer to see INPUT here.
> echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
[...]
> +$(API_EXAMPLES):
> + $(Q)mkdir -p $(RTE_OUTPUT)/doc/html
> + @echo "/**" > $(API_EXAMPLES)
> + @echo "@page examples DPDK Example Programs" >> $(API_EXAMPLES)
> + @echo "" >> $(API_EXAMPLES)
> + @find examples -type f -name "*.c" | awk '{ print "@example", $$0 }' >> $(API_EXAMPLES)
May I suggest this simpler syntax?
find examples -type f -name '*.c' -printf '@example %p\n'
Please prefer simple quotes where possible.
On 2/8/2017 12:08 PM, Thomas Monjalon wrote:
> 2017-01-27 17:37, Ferruh Yigit:
>> These files are linked to API documentation as usage samples, list of
>> files created automatically during doc creation.
>>
>> Remove manually updated old one.
>>
>> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> [...]
>> +API_EXAMPLES := $(RTE_OUTPUT)/doc/html/examples.dox
>
> I feel it should be in $(RTE_OUTPUT)/doc/ because the doc could be generated
> in another format (not HTML only).
Not sure, the rules use this file creates hardcoded
$(RTE_OUTPUT)/doc/html/ folder. Right now only user of this file is html
api document.
Putting this file to the root build/doc folder will work as fine, but I
think that file will look ugly there.
>
> [...]
>
>> @echo 'doxygen for API...'
>> $(Q)mkdir -p $(RTE_OUTPUT)/doc/html
>> $(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf && \
>> + echo INPUT += $(API_EXAMPLES) && \
>> printf 'PROJECT_NUMBER = ' && \
>> $(MAKE) -rR showversion && \
>
> It would be nicer to see INPUT here.
OK
>
>> echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
>
> [...]
>
>> +$(API_EXAMPLES):
>> + $(Q)mkdir -p $(RTE_OUTPUT)/doc/html
>> + @echo "/**" > $(API_EXAMPLES)
>> + @echo "@page examples DPDK Example Programs" >> $(API_EXAMPLES)
>> + @echo "" >> $(API_EXAMPLES)
>> + @find examples -type f -name "*.c" | awk '{ print "@example", $$0 }' >> $(API_EXAMPLES)
>
> May I suggest this simpler syntax?
> find examples -type f -name '*.c' -printf '@example %p\n'
Looks better, thanks.
I will send a new version soon.
>
> Please prefer simple quotes where possible.
>
@@ -30,7 +30,6 @@
PROJECT_NAME = DPDK
INPUT = doc/api/doxy-api-index.md \
- doc/api/examples.dox \
drivers/net/bonding \
lib/librte_eal/common/include \
lib/librte_eal/common/include/generic \
deleted file mode 100644
@@ -1,115 +0,0 @@
-/**
-@page examples DPDK Example Programs
-
-@example bond/main.c
-@example cmdline/commands.c
-@example cmdline/main.c
-@example cmdline/parse_obj_list.c
-@example distributor/main.c
-@example dpdk_qat/crypto.c
-@example dpdk_qat/main.c
-@example ethtool/ethtool-app/ethapp.c
-@example ethtool/ethtool-app/main.c
-@example ethtool/lib/rte_ethtool.c
-@example exception_path/main.c
-@example helloworld/main.c
-@example ip_fragmentation/main.c
-@example ip_pipeline/config_check.c
-@example ip_pipeline/config_parse.c
-@example ip_pipeline/config_parse_tm.c
-@example ip_pipeline/cpu_core_map.c
-@example ip_pipeline/init.c
-@example ip_pipeline/main.c
-@example ip_pipeline/pipeline/pipeline_common_be.c
-@example ip_pipeline/pipeline/pipeline_common_fe.c
-@example ip_pipeline/pipeline/pipeline_firewall_be.c
-@example ip_pipeline/pipeline/pipeline_firewall.c
-@example ip_pipeline/pipeline/pipeline_flow_actions_be.c
-@example ip_pipeline/pipeline/pipeline_flow_actions.c
-@example ip_pipeline/pipeline/pipeline_flow_classification_be.c
-@example ip_pipeline/pipeline/pipeline_flow_classification.c
-@example ip_pipeline/pipeline/pipeline_master_be.c
-@example ip_pipeline/pipeline/pipeline_master.c
-@example ip_pipeline/pipeline/pipeline_passthrough_be.c
-@example ip_pipeline/pipeline/pipeline_passthrough.c
-@example ip_pipeline/pipeline/pipeline_routing_be.c
-@example ip_pipeline/pipeline/pipeline_routing.c
-@example ip_pipeline/thread.c
-@example ip_pipeline/thread_fe.c
-@example ip_reassembly/main.c
-@example ipv4_multicast/main.c
-@example kni/main.c
-@example l2fwd-crypto/main.c
-@example l2fwd-jobstats/main.c
-@example l2fwd-keepalive/main.c
-@example l2fwd/main.c
-@example l3fwd-acl/main.c
-@example l3fwd/main.c
-@example l3fwd-power/main.c
-@example l3fwd-vf/main.c
-@example link_status_interrupt/main.c
-@example load_balancer/config.c
-@example load_balancer/init.c
-@example load_balancer/main.c
-@example load_balancer/runtime.c
-@example flow_distributor/distributor/args.c
-@example flow_distributor/distributor/init.c
-@example flow_distributor/distributor/main.c
-@example flow_distributor/node/node.c
-@example multi_process/client_server_mp/mp_client/client.c
-@example multi_process/client_server_mp/mp_server/args.c
-@example multi_process/client_server_mp/mp_server/init.c
-@example multi_process/client_server_mp/mp_server/main.c
-@example multi_process/l2fwd_fork/flib.c
-@example multi_process/l2fwd_fork/main.c
-@example multi_process/simple_mp/main.c
-@example multi_process/simple_mp/mp_commands.c
-@example multi_process/symmetric_mp/main.c
-@example netmap_compat/bridge/bridge.c
-@example netmap_compat/lib/compat_netmap.c
-@example packet_ordering/main.c
-@example performance-thread/common/arch/x86/ctx.c
-@example performance-thread/common/lthread.c
-@example performance-thread/common/lthread_cond.c
-@example performance-thread/common/lthread_diag.c
-@example performance-thread/common/lthread_mutex.c
-@example performance-thread/common/lthread_sched.c
-@example performance-thread/common/lthread_tls.c
-@example performance-thread/l3fwd-thread/main.c
-@example performance-thread/pthread_shim/main.c
-@example performance-thread/pthread_shim/pthread_shim.c
-@example ptpclient/ptpclient.c
-@example qos_meter/main.c
-@example qos_meter/rte_policer.c
-@example qos_sched/app_thread.c
-@example qos_sched/args.c
-@example qos_sched/cfg_file.c
-@example qos_sched/cmdline.c
-@example qos_sched/init.c
-@example qos_sched/main.c
-@example qos_sched/stats.c
-@example quota_watermark/qw/args.c
-@example quota_watermark/qwctl/commands.c
-@example quota_watermark/qwctl/qwctl.c
-@example quota_watermark/qw/init.c
-@example quota_watermark/qw/main.c
-@example rxtx_callbacks/main.c
-@example skeleton/basicfwd.c
-@example tep_termination/main.c
-@example tep_termination/vxlan.c
-@example tep_termination/vxlan_setup.c
-@example timer/main.c
-@example vhost/main.c
-@example vhost_xen/main.c
-@example vhost_xen/vhost_monitor.c
-@example vhost_xen/xenstore_parse.c
-@example vmdq_dcb/main.c
-@example vmdq/main.c
-@example vm_power_manager/channel_manager.c
-@example vm_power_manager/channel_monitor.c
-@example vm_power_manager/guest_cli/main.c
-@example vm_power_manager/guest_cli/vm_power_cli_guest.c
-@example vm_power_manager/main.c
-@example vm_power_manager/power_manager.c
-@example vm_power_manager/vm_power_cli.c
-*/
@@ -54,6 +54,8 @@ RTE_PDF_DPI ?= 300
RTE_GUIDES := $(filter %/, $(wildcard $(RTE_SDK)/doc/guides/*/))
+API_EXAMPLES := $(RTE_OUTPUT)/doc/html/examples.dox
+
.PHONY: help
help:
@cat $(RTE_SDK)/doc/build-sdk-quick.txt
@@ -66,10 +68,11 @@ all: api-html guides-html guides-pdf
clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean
.PHONY: api-html
-api-html: api-html-clean
+api-html: api-html-clean $(API_EXAMPLES)
@echo 'doxygen for API...'
$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
$(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf && \
+ echo INPUT += $(API_EXAMPLES) && \
printf 'PROJECT_NUMBER = ' && \
$(MAKE) -rR showversion && \
echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
@@ -83,8 +86,17 @@ api-html: api-html-clean
.PHONY: api-html-clean
api-html-clean:
$(Q)rm -f $(RTE_OUTPUT)/doc/html/api/*
+ $(Q)rm -f $(API_EXAMPLES)
$(Q)rmdir -p --ignore-fail-on-non-empty $(RTE_OUTPUT)/doc/html/api 2>&- || true
+$(API_EXAMPLES):
+ $(Q)mkdir -p $(RTE_OUTPUT)/doc/html
+ @echo "/**" > $(API_EXAMPLES)
+ @echo "@page examples DPDK Example Programs" >> $(API_EXAMPLES)
+ @echo "" >> $(API_EXAMPLES)
+ @find examples -type f -name "*.c" | awk '{ print "@example", $$0 }' >> $(API_EXAMPLES)
+ @echo "*/" >> $(API_EXAMPLES)
+
guides-pdf-clean: guides-pdf-img-clean
guides-pdf-img-clean:
$(Q)rm -f $(RTE_SDK)/doc/guides/*/img/*.pdf