docs: better docs, mv doxygen to sphinx

This patch refactors the VPP sphinx docs
in order to make it easier to consume
for external readers as well as VPP developers.

It also makes sphinx the single source
of documentation, which simplifies maintenance
and operation.

Most important updates are:

- reformat the existing documentation as rst
- split RELEASE.md and move it into separate rst files
- remove section 'events'
- remove section 'archive'
- remove section 'related projects'
- remove section 'feature by release'
- remove section 'Various links'
- make (Configuration reference, CLI docs,
  developer docs) top level items in the list
- move 'Use Cases' as part of 'About VPP'
- move 'Troubleshooting' as part of 'Getting Started'
- move test framework docs into 'Developer Documentation'
- add a 'Contributing' section for gerrit,
  docs and other contributer related infos
- deprecate doxygen and test-docs targets
- redirect the "make doxygen" target to "make docs"

Type: refactor

Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>

1 files changed, 0 insertions, 270 deletions

diff --git a/doxygen/Makefile b/doxygen/Makefile
deleted file mode 100644
index e399b404a26..00000000000
--- a/doxygen/Makefile
+++ /dev/null
@@ -1,270 +0,0 @@
-# Copyright (c) 2016 Comcast Cable Communications Management, LLC.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-#
-# Build the documentation
-#
-
-# Default target
-.PHONY: all
-all: doxygen
-
-# These should be passed in by the root Makefile
-WS_ROOT ?= $(CURDIR)/..
-BR ?= $(WS_ROOT)/build-root
-
-# We support MacOS for docs generation
-ifeq ($(shell uname),Darwin)
-OS_ID = darwin
-endif
-
-# Work out the OS if we haven't already
-OS_ID ?= $(shell grep '^ID=' /etc/os-release | cut -f2- -d= | sed -e 's/\"//g')
-
-# Package dependencies
-DOC_DEB_DEPENDS = doxygen graphviz python3-pyparsing python3-jinja2
-DOC_RPM_DEPENDS = doxygen graphviz python3-pyparsing python3-jinja2
-DOC_MAC_BIN_DEPENDS = doxygen dot git
-DOC_MAC_PY_DEPENDS = pyparsing jinja2
-
-# Doxygen configuration and our utility scripts
-DOXY_DIR ?= $(WS_ROOT)/doxygen
-
-# Primary source directories
-DOXY_SRC ?= $(WS_ROOT)/src
-DOXY_SRC_DIRECTORIES = \
-	$(shell find $(DOXY_SRC) -name '*.md' -print | xargs dirname \
-	| sort | uniq) \
-	$(DOXY_SRC)/vppinfra \
-	$(DOXY_SRC)/svm \
-	$(DOXY_SRC)/vlib \
-	$(DOXY_SRC)/vlibapi \
-	$(DOXY_SRC)/vlibmemory \
-	$(DOXY_SRC)/vnet \
-	$(DOXY_SRC)/vpp \
-	$(DOXY_SRC)/vpp-api \
-	$(DOXY_SRC)/examples
-
-# Input directories and files
-DOXY_INPUT ?= \
-	$(wildcard $(WS_ROOT)/*.md) \
-	$(wildcard $(DOXY_DIR)/*.md) \
-	$(DOXY_SRC_DIRECTORIES) \
-	$(DOXY_SRC)/plugins \
-	extras
-
-# Strip leading workspace path from input names
-DOXY_INPUT := $(subst $(WS_ROOT)/,,$(DOXY_INPUT))
-
-# Files to exclude, from pre-Doxygen steps, eg because they're
-# selectively compiled.
-# Examples would be to exclude non-DPDK related sources when
-# there's a DPDK equivalent that conflicts.
-# These must be left-anchored paths for the regexp below to work.
-DOXY_EXCLUDE ?= \
-	$(DOXY_SRC)/vpp-api/lua
-
-# Generate a regexp for filenames to exclude
-DOXY_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_EXCLUDE))' | sed -e 's/ /|/g')))
-
-# Include all the normal source directories in the include file path
-DOXY_INCLUDE_PATH = $(DOXY_SRC_DIRECTORIES)
-
-# Find API header directories and include them in the header path.
-# This is only useful if VPP and plugins are already built; nothing
-# here depends on those targets. We don't build documentation for these
-# header files, they're just added to the INCLUDE search path for Doxygen.
-_vpp_br = $(shell find "$(BR)" -maxdepth 1 -type d \
-	'(' -name build-vpp_debug-native -o -name build-vpp-native ')' -print \
-	| sed -e 's@^$(WS_ROOT)/*@@' -e 1q)
-ifneq ($(strip $(_vpp_br)),)
-DOXY_INCLUDE_PATH += \
-	$(_vpp_br)/vlib-api \
-	$(_vpp_br)/vpp
-# Also include any plugin directories that exist
-DOXY_INCLUDE_PATH += \
-	$(shell find $(WS_ROOT)/$(_vpp_br)/plugins -maxdepth 1 -type d | sed -e 's@^$(WS_ROOT)/*@@')
-endif
-
-# Discover if we have CPP available
-_cpp = $(shell which cpp)
-ifneq ($(strip $(_cpp)),)
-# Add whatever directories CPP normally includes to the header path
-DOXY_INCLUDE_PATH += $(shell set -e; $(_cpp) -v </dev/null 2>&1 | awk 'f&&/^ /{print $$1} /^\#include/{f=1}')
-endif
-
-# Target directory for doxygen output
-DOXY_OUTPUT ?= $(BR)/docs
-
-# Siphoned fragments end up in here
-SIPHON_INPUT ?= $(DOXY_OUTPUT)/siphon_fragments
-
-# Siphoned fragements are processed into here
-SIPHON_OUTPUT ?= $(DOXY_OUTPUT)/siphon_docs
-
-# Extra document inputs that are processed in addition to DOXY_INPUT
-EXTRA_DOXY_INPUT += $(SIPHON_OUTPUT)
-
-# All the siphon types we know about
-SIPHONS ?= clicmd syscfg
-
-SIPHON_FILES = $(addprefix $(SIPHON_INPUT)/,$(addsuffix .siphon,$(SIPHONS)))
-SIPHON_DOCS = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .md,$(SIPHONS)))
-SIPHON_ITEMLIST = $(addprefix $(SIPHON_OUTPUT)/,$(addsuffix .itemlist,$(filter clicmd,$(SIPHONS))))
-
-$(BR)/.doxygen-bootstrap.ok: Makefile
-	@echo "Checking whether dependencies for Doxygen are installed..."
-ifeq ($(OS_ID),ubuntu)
-	@set -e; inst=; \
-		for i in $(DOC_DEB_DEPENDS); do \
-			dpkg-query --show $$i >/dev/null 2>&1 || inst="$$inst $$i"; \
-		done; \
-		if [ "$$inst" ]; then \
-			sudo apt-get update; \
-			sudo apt-get $(CONFIRM) $(FORCE) install $$inst; \
-		fi
-	@if [ ! -s /usr/lib/graphviz/config6a ]; then \
-		echo "Rebuilding system Graphviz configuration."; \
-		sudo dot -c; \
-	fi
-else ifneq ("$(wildcard /etc/redhat-release)","")
-	@sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS)
-else ifeq ($(OS_ID),darwin)
-	@set -e; \
-	for bin in $(DOC_MAC_BIN_DEPENDS); do \
-		which -s $${bin} || (\
-			echo "Program '$${bin}' not found, please install it."; \
-			false; \
-		); \
-	done
-	@set -e; \
-	for py in $(DOC_MAC_PY_DEPENDS); do \
-		python -c "import $${py}" >/dev/null 2>&1 || (\
-			echo "Python package '$${py}' not found, please install it."; \
-			false; \
-		); \
-	done
-else
-	$(error "Building documentation currently works only on Ubuntu, CentOS, MacOS and OpenSUSE systems.")
-endif
-	@touch $@
-
-.PHONY: bootstrap-doxygen
-bootstrap-doxygen: $(BR)/.doxygen-bootstrap.ok
-
-.DELETE_ON_ERROR: $(BR)/.doxygen-siphon.dep
-$(BR)/.doxygen-siphon.dep: Makefile \
-		$(addprefix,$(WSROOT),$(DOXY_INPUT))
-	@echo "Building siphon dependencies..."
-	@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)' \
-			| sed -e "s/^/\$$(SIPHON_FILES): /" \
-			>> $@; \
-	done
-
-# Include the source -> siphon dependencies
--include $(BR)/.doxygen-siphon.dep
-
-# Generate .siphon files that contain fragments of source file that
-# relate to the siphons we support.
-.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
-	@echo "Collating source file list for siphoning..."
-	@for input in $(DOXY_INPUT); do \
-		cd "$(WS_ROOT)"; \
-		find "$$input" -type f \
-			\( -name '*.[ch]' -or -name '*.dox' \) -print \
-			| grep -v -E '^src/examples/' \
-			| grep -v -E '^$(DOXY_EXCLUDE_REGEXP)' \
-			>> $(SIPHON_INPUT)/files; \
-	done
-	@echo "Generating siphons..."
-	@set -e; \
-	cd "$(WS_ROOT)"; \
-	$(DOXY_DIR)/siphon-generate \
-		--output="$(SIPHON_INPUT)" \
-		"@$(SIPHON_INPUT)/files"
-
-# Evaluate this to build a siphon doc output target for each desired
-# output type:
-# $(eval $(call siphon-process,file_extension,output_type_name))
-define siphon-process
-$(SIPHON_OUTPUT)/%.$(1): $(SIPHON_INPUT)/%.siphon \
-		$(DOXY_DIR)/siphon-process \
-		$(wildcard $(DOXY_DIR)/siphon/*.py) \
-		$(wildcard $(DOXY_DIR)/siphon_templates/$(2)/*/*.$(1))
-	@echo "Processing siphon for $(2) from $$(notdir $$<)..."
-	@set -e; \
-	cd "$(WS_ROOT)"; \
-	$(DOXY_DIR)/siphon-process \
-		--type=$$(basename $$(notdir $$<)) \
-		--format=$(2) \
-		--output="$$@" \
-		"$$<"
-endef
-
-# Process the .siphon source fragments and render them into doxygen flavored
-# markdown documentation
-.DELETE_ON_ERROR: $(SIPHON_DOCS)
-$(eval $(call siphon-process,md,markdown))
-
-# Process the .siphon source fragments and render them into a list of cli
-# commands.
-.DELETE_ON_ERROR: $(SIPHON_ITEMLIST)
-$(eval $(call siphon-process,itemlist,itemlist))
-
-# This target can be used just to generate the siphoned things
-.PHONY: doxygen-siphon
-doxygen-siphon: $(SIPHON_DOCS) $(SIPHON_ITEMLIST)
-
-# Generate the doxygen docs
-.PHONY: doxygen
-doxygen: $(SIPHON_DOCS)
-	@mkdir -p "$(DOXY_OUTPUT)"
-	@echo "Running Doxygen..."
-	set -e; cd "$(WS_ROOT)"; \
-	    ROOT="$(WS_ROOT)" \
-	    BUILD_ROOT="$(BR)" \
-	    INPUT="$(addprefix $(WS_ROOT)/,$(DOXY_INPUT)) $(EXTRA_DOXY_INPUT)" \
-	    INCLUDE_PATH="$(DOXY_INCLUDE_PATH)" \
-	    EXCLUDE="$(DOXY_EXCLUDE)" \
-	    HTML=YES \
-	    VERSION="`git describe --tags --dirty`" \
-	    doxygen $(DOXY_DIR)/doxygen.cfg
-
-.PHONY: wipe-doxygen
-wipe-doxygen:
-	@rm -rf $(BR)/docs
-	@rm -rf $(BR)/.doxygen-siphon.dep
-	@rm -rf $(BR)/.doxygen-bootstrap.ok
-	@rm -rf $(DOXY_DIR)/siphon/__pycache__
-
-.PHONY: clean
-clean: wipe-doxygen