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>

diff --git a/README.md b/README.md
index cf43a4d..8520b39 100644 (file)
--- 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 92fa363..ffce3c1 100644 (file)
--- 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 2e87c87..4030343 100644 (file)
--- 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 1333ed7..3e86b17 100644 (file)
--- 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
similarity index 98%
rename from src/vnet/span/span.md
rename to src/vnet/span/span_doc.md
index ee3f814..46480b2 100644 (file)
--- 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.