doc: generate HTML for API with doxygen
authorThomas Monjalon <thomas.monjalon@6wind.com>
Fri, 19 Apr 2013 10:34:40 +0000 (12:34 +0200)
committerDavid Marchand <david.marchand@6wind.com>
Wed, 26 Feb 2014 10:01:13 +0000 (11:01 +0100)
- 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>
doc/doxy-api-index.md [new file with mode: 0644]
doc/doxy-api.conf [new file with mode: 0644]
doc/doxy-html-custom.sh [new file with mode: 0755]
mk/rte.sdkdoc.mk
mk/rte.sdkroot.mk

diff --git a/doc/doxy-api-index.md b/doc/doxy-api-index.md
new file mode 100644 (file)
index 0000000..c4eab24
--- /dev/null
@@ -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)
diff --git a/doc/doxy-api.conf b/doc/doxy-api.conf
new file mode 100644 (file)
index 0000000..5d3e4ca
--- /dev/null
@@ -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 (executable)
index 0000000..e684a75
--- /dev/null
@@ -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
index f44a6b7..d47a2b5 100644 (file)
@@ -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
index 1e3110b..22e8817 100644 (file)
@@ -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: