d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: generate HTML for API with doxygen

Browse Source 
- 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 <thomas.monjalon@6wind.com>
Acked-by: Olivier Matz <olivier.matz@6wind.com>
Acked-by: David Marchand <david.marchand@6wind.com>
This commit is contained in:
Thomas Monjalon 2013-04-19 12:34:40 +02:00 committed by David Marchand
parent ee801f6cc7
commit 9bf486e606
5 changed files with 236 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
doc/doxy-api-index.md Normal file
View File

@ -0,0 +1,111 @@
API {#index}
===
<!--
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.
-->
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)

62
doc/doxy-api.conf Normal file
View File

@ -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

36
doc/doxy-html-custom.sh Executable file
View File

@ -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

27
mk/rte.sdkdoc.mk
View File

@ -1,6 +1,7 @@
# BSD LICENSE # BSD LICENSE
# #
# Copyright(c) 2010-2014 Intel Corporation. All rights reserved. # Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
# Copyright(c) 2013 6WIND S.A.
# All rights reserved. # All rights reserved.
# #
# Redistribution and use in source and binary forms, with or without # Redistribution and use in source and binary forms, with or without
@ -35,8 +36,26 @@ $(error "Cannot use T= with doc target")
endif endif
endif endif
.PHONY: doc .PHONY: all
doc: all: htmlapi
.PHONY: doc-clean .PHONY: clean
doc-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

7
mk/rte.sdkroot.mk
View File

@ -101,9 +101,10 @@ testall:
install uninstall: install uninstall:
$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@ $(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@
.PHONY: doc doc-clean .PHONY: doc
doc doc-clean: doc: doc-all
$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $@ doc-%:
$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $*
.PHONY: depdirs depgraph .PHONY: depdirs depgraph
depdirs depgraph: depdirs depgraph: