aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChris Luke <chrisy@flirble.org>2016-12-28 09:44:47 -0500
committerDamjan Marion <dmarion.lists@gmail.com>2016-12-28 15:48:08 +0000
commitfdc62abdc113ea63dc867375bd49ef3043dcd290 (patch)
tree58fa46de0a30e69db796564890c3daa2830953c7
parent37d77e9edbf845de23d41c343c11b34a575761ff (diff)
Repair Doxygen build infrastructure
After Gerrit 4430 much of the documentation failed to build, but silently so it was easily missed; equally missing that several paths have been missing for a while. - Correct paths after directory tree changes. - Doxygen now bails when input paths don't exist. - Fix up some of the less deranged entries in the documentation index. - Exclude the LUA tree, its documentation is a mess. Change-Id: I35e6b433feee5e05bca772d93aa1635c724db734 Signed-off-by: Chris Luke <chrisy@flirble.org>
-rw-r--r--README.md30
-rw-r--r--doxygen/Makefile38
-rw-r--r--doxygen/user_doc.md2
-rw-r--r--src/vnet/bfd/bfd_doc.md4
-rw-r--r--src/vnet/span/span_doc.md (renamed from src/vnet/span/span.md)2
5 files changed, 48 insertions, 28 deletions
diff --git a/README.md b/README.md
index cf43a4df..8520b395 100644
--- a/README.md
+++ b/README.md
@@ -30,22 +30,22 @@ Directory name | Description
build-root | Build output directory
doxygen | Documentation generator configuration
dpdk | DPDK patches and build infrastructure
- g2 | Event log visualization tool
- perftool | Performance tool
-@ref plugins | VPP bundled plugins directory
-@ref svm | Shared virtual memory allocation library
+@ref plugins | Not-yet-relocated VPP bundled plugins directory
+@ref src | VPP source code
+@ref src/plugins | VPP bundled plugins directory
+@ref src/svm | Shared virtual memory allocation library
+ src/tests | Unit tests
+ src/vat | VPP API test program
+@ref src/vlib | VPP application library
+@ref src/vlibapi | VPP API library
+@ref src/vlibmemory | VPP Memory management
+@ref src/vlibsocket | VPP Socket I/O
+@ref src/vnet | VPP networking
+@ref src/vpp | VPP application
+@ref src/vpp-api | VPP application API bindings
+@ref src/vppinfra | VPP core library
test | Unit tests
-@ref vlib | VPP application library source
-@ref vlib-api | VPP API library source
-@ref vnet | VPP networking source
-@ref vpp | VPP application source
-@ref vpp-api | VPP application API source
- vppapigen | VPP API generator source
- vpp-api-test | VPP API test program source
-@ref vppinfra | VPP core library source
-
-(If the page you are viewing is not generated by Doxygen then
-ignore any @@ref labels in the above table.)
+@ref vpp-api | Not-yet-relocated API bindings
## Getting started
diff --git a/doxygen/Makefile b/doxygen/Makefile
index 92fa3635..ffce3c13 100644
--- a/doxygen/Makefile
+++ b/doxygen/Makefile
@@ -42,13 +42,17 @@ DOC_MAC_PY_DEPENDS = pyparsing jinja2
DOXY_DIR ?= $(WS_ROOT)/doxygen
# Primary source directories
+DOXY_SRC ?= src
DOXY_SRC_DIRECTORIES = \
- vppinfra \
- svm \
- vlib \
- vlib-api \
- vnet \
- vpp \
+ $(DOXY_SRC)/vppinfra \
+ $(DOXY_SRC)/svm \
+ $(DOXY_SRC)/vlib \
+ $(DOXY_SRC)/vlibapi \
+ $(DOXY_SRC)/vlibmemory \
+ $(DOXY_SRC)/vlibsocket \
+ $(DOXY_SRC)/vnet \
+ $(DOXY_SRC)/vpp \
+ $(DOXY_SRC)/vpp-api \
vpp-api
# Input directories and files
@@ -56,6 +60,7 @@ DOXY_INPUT ?= \
$(wildcard $(WS_ROOT)/*.md) \
$(wildcard $(DOXY_DIR)/*.md) \
$(DOXY_SRC_DIRECTORIES) \
+ $(DOXY_SRC)/plugins \
plugins
# Strip leading workspace path from input names
@@ -67,9 +72,10 @@ DOXY_INPUT := $(subst $(WS_ROOT)/,,$(DOXY_INPUT))
# there's a DPDK equivalent that conflicts.
# These must be left-anchored paths for the regexp below to work.
DOXY_EXCLUDE ?= \
- vlib/vlib/buffer.c \
- vlib/example \
- plugins/sample-plugin
+ $(DOXY_SRC)/vlib/vlib/buffer.c \
+ $(DOXY_SRC)/vlib/example \
+ plugins/sample-plugin \
+ vpp-api/lua
# Generate a regexp for filenames to exclude
DOXY_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_EXCLUDE))' | sed -e 's/ /|/g')))
@@ -164,9 +170,11 @@ endif
bootstrap-doxygen: $(BR)/.doxygen-bootstrap.ok
.DELETE_ON_ERROR: $(BR)/.doxygen-siphon.dep
-$(BR)/.doxygen-siphon.dep: Makefile
+$(BR)/.doxygen-siphon.dep: Makefile \
+ $(addprefix,$(WSROOT),$(DOXY_INPUT))
@echo "Building siphon dependencies..."
- @set -e; rm -f "$@"; for input in $(DOXY_INPUT); do \
+ @rm -f "$@"; for input in $(DOXY_INPUT); do \
+ [ -e "$(WS_ROOT)/$$input" ] && \
find "$(WS_ROOT)/$$input" -type f \
\( -name '*.[ch]' -or -name '*.dox' \) -print \
| grep -v -E '^$(WS_ROOT)/$(DOXY_EXCLUDE_REGEXP)' \
@@ -182,7 +190,15 @@ $(BR)/.doxygen-siphon.dep: Makefile
.NOTPARALLEL: $(SIPHON_FILES)
$(SIPHON_FILES): $(BR)/.doxygen-bootstrap.ok \
$(DOXY_DIR)/siphon-generate \
+ $(addprefix,$(WSROOT),$(DOXY_INPUT)) \
$(wildcard $(DOXY_DIR)/siphon/*.py)
+ @echo "Validating source tree..."
+ @set -e; for input in $(DOXY_INPUT); do \
+ if [ ! -e "$(WS_ROOT)/$$input" ]; then \
+ echo "ERROR: Input path '$$input' does not exist." >&2; \
+ exit 1; \
+ fi; \
+ done
@rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
@mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
@touch $(SIPHON_INPUT)/files
diff --git a/doxygen/user_doc.md b/doxygen/user_doc.md
index 2e87c877..40303439 100644
--- a/doxygen/user_doc.md
+++ b/doxygen/user_doc.md
@@ -12,3 +12,5 @@ Several modules provide operational, dataplane-user focused documentation.
- @subpage ioam_plugin_doc
- @subpage lb_plugin_doc
- @subpage flowperpkt_plugin_doc
+- @subpage span_doc
+- @subpage bfd_doc
diff --git a/src/vnet/bfd/bfd_doc.md b/src/vnet/bfd/bfd_doc.md
index 1333ed77..3e86b178 100644
--- a/src/vnet/bfd/bfd_doc.md
+++ b/src/vnet/bfd/bfd_doc.md
@@ -1 +1,3 @@
-TODO
+# BFD Notes {#bfd_doc}
+
+@todo Someone needs to produce this or remove the stub file.
diff --git a/src/vnet/span/span.md b/src/vnet/span/span_doc.md
index ee3f814f..46480b28 100644
--- a/src/vnet/span/span.md
+++ b/src/vnet/span/span_doc.md
@@ -1,4 +1,4 @@
-# VPP SPAN implementation
+# VPP SPAN implementation {#span_doc}
This is a memo intended to contain documentation of the VPP SPAN implementation.
Everything that is not directly obvious should come here.