- 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 at 6wind.com>
---
doc/doxy-api-index.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++
doc/doxy-api.conf | 59 +++++++++++++++++++++++++++
doc/doxy-html-custom.sh | 6 +++
mk/rte.sdkdoc.mk | 27 +++++++++++--
mk/rte.sdkroot.mk | 7 ++--
5 files changed, 193 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 0000000..de872ec
--- /dev/null
+++ b/doc/doxy-api-index.md
@@ -0,0 +1,101 @@
+<!--
+ BSD LICENSE
+
+ Copyright(c) 2013 6WIND.
+
+ 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.
+-->
+
+# API {#index}
+
+There are many libraries, so their headers may be grouped by topics:
+
+- **device**:
+ [ethdev] (@ref rte_ethdev.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)
+
+- **network stack**:
+ [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)
+
+- **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)
+
+- **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),
+ [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 0000000..e5ce102
--- /dev/null
+++ b/doc/doxy-api.conf
@@ -0,0 +1,59 @@
+# BSD LICENSE
+#
+# Copyright(c) 2013 6WIND.
+#
+# 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_lpm \
+ lib/librte_malloc \
+ lib/librte_mbuf \
+ lib/librte_mempool \
+ lib/librte_net \
+ lib/librte_ring \
+ 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 0000000..2465cc2
--- /dev/null
+++ b/doc/doxy-html-custom.sh
@@ -0,0 +1,6 @@
+#! /bin/sh -e
+
+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 57eb8e6..edae1e7 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -1,6 +1,7 @@
# BSD LICENSE
#
# Copyright(c) 2010-2012 Intel Corporation. All rights reserved.
+# Copyright(c) 2013 6WIND.
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
@@ -37,8 +38,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 fe0070e..f555e33 100644
--- a/mk/rte.sdkroot.mk
+++ b/mk/rte.sdkroot.mk
@@ -103,9 +103,10 @@ testall testimport:
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:
--
1.7.10.4
