From 9bf486e606b0ba66b7f64cb57cdc640a43f8317c Mon Sep 17 00:00:00 2001 From: Thomas Monjalon Date: Fri, 19 Apr 2013 12:34:40 +0200 Subject: [PATCH] doc: generate HTML for API with doxygen - add index page - add doxygen configuration for API - add doxygen CSS customization applied by a script - HTML generation via make rules The configuration is splitted in a static file and a make rule in order to dynamically configure output format and path. Signed-off-by: Thomas Monjalon Acked-by: Olivier Matz Acked-by: David Marchand --- doc/doxy-api-index.md | 111 ++++++++++++++++++++++++++++++++++++++++ doc/doxy-api.conf | 62 ++++++++++++++++++++++ doc/doxy-html-custom.sh | 36 +++++++++++++ mk/rte.sdkdoc.mk | 27 ++++++++-- mk/rte.sdkroot.mk | 7 +-- 5 files changed, 236 insertions(+), 7 deletions(-) create mode 100644 doc/doxy-api-index.md create mode 100644 doc/doxy-api.conf create mode 100755 doc/doxy-html-custom.sh diff --git a/doc/doxy-api-index.md b/doc/doxy-api-index.md new file mode 100644 index 0000000000..c4eab248bb --- /dev/null +++ b/doc/doxy-api-index.md @@ -0,0 +1,111 @@ +API {#index} +=== + + + +There are many libraries, so their headers may be grouped by topics: + +- **device**: + [ethdev] (@ref rte_ethdev.h), + [KNI] (@ref rte_kni.h), + [PCI] (@ref rte_pci.h), + [PCI IDs] (@ref rte_pci_dev_ids.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) + +- **timers**: + [cycles] (@ref rte_cycles.h), + [timer] (@ref rte_timer.h), + [alarm] (@ref rte_alarm.h) + +- **locks**: + [atomic] (@ref rte_atomic.h), + [rwlock] (@ref rte_rwlock.h), + [spinlock] (@ref rte_spinlock.h) + +- **CPU arch**: + [branch prediction] (@ref rte_branch_prediction.h), + [cache prefetch] (@ref rte_prefetch.h), + [byte order] (@ref rte_byteorder.h), + [CPU flags] (@ref rte_cpuflags.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), + [power/freq] (@ref rte_power.h) + +- **layers**: + [ethernet] (@ref rte_ether.h), + [IP] (@ref rte_ip.h), + [SCTP] (@ref rte_sctp.h), + [TCP] (@ref rte_tcp.h), + [UDP] (@ref rte_udp.h), + [LPM route] (@ref rte_lpm.h) + +- **QoS**: + [metering] (@ref rte_meter.h), + [scheduler] (@ref rte_sched.h), + [RED congestion] (@ref rte_red.h) + +- **hashes**: + [hash] (@ref rte_hash.h), + [jhash] (@ref rte_jhash.h), + [FBK hash] (@ref rte_fbk_hash.h), + [CRC hash] (@ref rte_hash_crc.h) + +- **containers**: + [mbuf] (@ref rte_mbuf.h), + [ring] (@ref rte_ring.h), + [tailq] (@ref rte_tailq.h), + [bitmap] (@ref rte_bitmap.h) + +- **debug**: + [debug] (@ref rte_debug.h), + [log] (@ref rte_log.h), + [warnings] (@ref rte_warnings.h), + [errno] (@ref rte_errno.h) + +- **misc**: + [EAL config] (@ref rte_eal.h), + [common] (@ref rte_common.h), + [approx fraction] (@ref rte_approx.h), + [random] (@ref rte_random.h), + [string] (@ref rte_string_fns.h), + [version] (@ref rte_version.h) diff --git a/doc/doxy-api.conf b/doc/doxy-api.conf new file mode 100644 index 0000000000..5d3e4cad84 --- /dev/null +++ b/doc/doxy-api.conf @@ -0,0 +1,62 @@ +# BSD LICENSE +# +# Copyright 2013 6WIND S.A. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: +# +# * Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in +# the documentation and/or other materials provided with the +# distribution. +# * Neither the name of 6WIND S.A. nor the names of its +# contributors may be used to endorse or promote products derived +# from this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +PROJECT_NAME = DPDK +INPUT = doc/doxy-api-index.md \ + lib/librte_eal/common/include \ + lib/librte_ether \ + lib/librte_hash \ + lib/librte_kni \ + lib/librte_lpm \ + lib/librte_malloc \ + lib/librte_mbuf \ + lib/librte_mempool \ + lib/librte_meter \ + lib/librte_net \ + lib/librte_power \ + lib/librte_ring \ + lib/librte_sched \ + lib/librte_timer +FILE_PATTERNS = rte_*.h \ + cmdline.h +PREDEFINED = __DOXYGEN__ + +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_STATIC = 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 diff --git a/doc/doxy-html-custom.sh b/doc/doxy-html-custom.sh new file mode 100755 index 0000000000..e684a75a07 --- /dev/null +++ b/doc/doxy-html-custom.sh @@ -0,0 +1,36 @@ +#! /bin/sh -e + +# BSD LICENSE +# +# Copyright 2013 6WIND S.A. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: +# +# * Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in +# the documentation and/or other materials provided with the +# distribution. +# * Neither the name of 6WIND S.A. nor the names of its +# contributors may be used to endorse or promote products derived +# from this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +CSS=$1 + +# space between item and its comment +echo 'dd td:first-child {padding-right: 2em;}' >> $CSS diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk index f44a6b7c50..d47a2b5729 100644 --- a/mk/rte.sdkdoc.mk +++ b/mk/rte.sdkdoc.mk @@ -1,6 +1,7 @@ # BSD LICENSE # # Copyright(c) 2010-2014 Intel Corporation. All rights reserved. +# Copyright(c) 2013 6WIND S.A. # All rights reserved. # # Redistribution and use in source and binary forms, with or without @@ -35,8 +36,26 @@ $(error "Cannot use T= with doc target") endif endif -.PHONY: doc -doc: +.PHONY: all +all: htmlapi -.PHONY: doc-clean -doc-clean: +.PHONY: clean +clean: htmlapi-clean + +.PHONY: htmlapi +htmlapi: htmlapi-clean + @echo 'doxygen for API...' + $(Q)mkdir -p $(RTE_OUTPUT)/doc/html + $(Q)(cat $(RTE_SDK)/doc/doxy-api.conf && \ + echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \ + echo HTML_OUTPUT = html/api && \ + echo GENERATE_HTML = YES && \ + echo GENERATE_LATEX = NO && \ + echo GENERATE_MAN = NO )| \ + doxygen - + $(Q)$(RTE_SDK)/doc/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css + +.PHONY: htmlapi-clean +htmlapi-clean: + $(Q)rm -f $O/doc/html/api/* + $(Q)rmdir -p --ignore-fail-on-non-empty $(RTE_OUTPUT)/doc/html/api 2>&- || true diff --git a/mk/rte.sdkroot.mk b/mk/rte.sdkroot.mk index 1e3110b051..22e88176f7 100644 --- a/mk/rte.sdkroot.mk +++ b/mk/rte.sdkroot.mk @@ -101,9 +101,10 @@ testall: install uninstall: $(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@ -.PHONY: doc doc-clean -doc doc-clean: - $(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $@ +.PHONY: doc +doc: doc-all +doc-%: + $(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $* .PHONY: depdirs depgraph depdirs depgraph: