Update test documentation.

- update IRB, IPv4, ipv6 doc
- revert 778c2765c8ea5c6628f6d668847f0b9ae06dbf3d

Change-Id: I9af5ed9329ce5fe01392cf28d5bf321cfc647e48
Signed-off-by: Matej Klotton <mklotton@cisco.com>

21 files changed, 40 insertions, 196 deletions

diff --git a/test/doc/Makefile b/test/doc/Makefile
index 3b4c02b8420..809abef846e 100644
--- a/test/doc/Makefile
+++ b/test/doc/Makefile
@@ -8,13 +8,15 @@ SPHINXBUILD = sphinx-build
 PAPER         =
 BUILD_DOC_ROOT = $(BR)/test-doc
 BUILD_DOC_DIR = $(BUILD_DOC_ROOT)/build
+API_DOC_GEN_DIR = $(BUILD_DOC_ROOT)/apidoc
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILD_DOC_DIR)/.sphinx-cache $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRC_DOC_DIR)
+ALLSPHINXOPTS   = -d $(BUILD_DOC_DIR)/.sphinx-cache $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(API_DOC_GEN_DIR) -c $(SRC_DOC_DIR)
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+INDEX_REL_PATH:=$(shell realpath --relative-to=$(API_DOC_GEN_DIR) $(SRC_DOC_DIR)/index.rst)
 IN_VENV:=$(shell if pip -V | grep "virtualenv" 2>&1 > /dev/null; then echo 1; else echo 0; fi)
 
 .PHONY: verify-virtualenv
@@ -23,6 +25,13 @@ ifeq ($(IN_VENV),0)
 	$(error "Not running inside virtualenv (are you running 'make test-doc' from root?)")
 endif
 
+.PHONY: regen-api-doc
+regen-api-doc: verify-virtualenv
+	@mkdir -p $(API_DOC_GEN_DIR)
+	#@echo ".. include:: $(INDEX_REL_PATH)" > $(API_DOC_GEN_DIR)/index.rst
+	@cp $(SRC_DOC_DIR)/index.rst $(API_DOC_GEN_DIR)
+	sphinx-apidoc -o $(API_DOC_GEN_DIR) ..
+
 .PHONY: help
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -58,44 +67,44 @@ wipe:
 	rm -rf $(BUILD_DOC_ROOT)
 
 .PHONY: html
-html: verify-virtualenv
+html: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILD_DOC_DIR)/html."
 
 .PHONY: dirhtml
-dirhtml: verify-virtualenv
+dirhtml: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILD_DOC_DIR)/dirhtml."
 
 .PHONY: singlehtml
-singlehtml: verify-virtualenv
+singlehtml: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILD_DOC_DIR)/singlehtml."
 
 .PHONY: pickle
-pickle: verify-virtualenv
+pickle: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 .PHONY: json
-json: verify-virtualenv
+json: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 .PHONY: htmlhelp
-htmlhelp: verify-virtualenv
+htmlhelp: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILD_DOC_DIR)/htmlhelp."
 
 .PHONY: qthelp
-qthelp: verify-virtualenv
+qthelp: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -105,7 +114,7 @@ qthelp: verify-virtualenv
 	@echo "# assistant -collectionFile $(BUILD_DOC_DIR)/qthelp/VPPtestframework.qhc"
 
 .PHONY: applehelp
-applehelp: verify-virtualenv
+applehelp: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/applehelp
 	@echo
 	@echo "Build finished. The help book is in $(BUILD_DOC_DIR)/applehelp."
@@ -114,7 +123,7 @@ applehelp: verify-virtualenv
 	      "bundle."
 
 .PHONY: devhelp
-devhelp: verify-virtualenv
+devhelp: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -124,7 +133,7 @@ devhelp: verify-virtualenv
 	@echo "# devhelp"
 
 .PHONY: epub
-epub: verify-virtualenv
+epub: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILD_DOC_DIR)/epub."
@@ -136,7 +145,7 @@ epub3:
 	@echo "Build finished. The epub3 file is in $(BUILD_DOC_DIR)/epub3."
 
 .PHONY: latex
-latex: verify-virtualenv
+latex: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILD_DOC_DIR)/latex."
@@ -144,33 +153,33 @@ latex: verify-virtualenv
 	      "(use \`make latexpdf' here to do that automatically)."
 
 .PHONY: latexpdf
-latexpdf: verify-virtualenv
+latexpdf: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILD_DOC_DIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILD_DOC_DIR)/latex."
 
 .PHONY: latexpdfja
-latexpdfja: verify-virtualenv
+latexpdfja: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILD_DOC_DIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILD_DOC_DIR)/latex."
 
 .PHONY: text
-text: verify-virtualenv
+text: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILD_DOC_DIR)/text."
 
 .PHONY: man
-man: verify-virtualenv
+man: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILD_DOC_DIR)/man."
 
 .PHONY: texinfo
-texinfo: verify-virtualenv
+texinfo: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILD_DOC_DIR)/texinfo."
@@ -178,57 +187,57 @@ texinfo: verify-virtualenv
 	      "(use \`make info' here to do that automatically)."
 
 .PHONY: info
-info: verify-virtualenv
+info: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILD_DOC_DIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILD_DOC_DIR)/texinfo."
 
 .PHONY: gettext
-gettext: verify-virtualenv
+gettext: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILD_DOC_DIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILD_DOC_DIR)/locale."
 
 .PHONY: changes
-changes: verify-virtualenv
+changes: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILD_DOC_DIR)/changes."
 
 .PHONY: linkcheck
-linkcheck: verify-virtualenv
+linkcheck: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILD_DOC_DIR)/linkcheck/output.txt."
 
 .PHONY: doctest
-doctest: verify-virtualenv
+doctest: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILD_DOC_DIR)/doctest/output.txt."
 
 .PHONY: coverage
-coverage: verify-virtualenv
+coverage: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/coverage
 	@echo "Testing of coverage in the sources finished, look at the " \
 	      "results in $(BUILD_DOC_DIR)/coverage/python.txt."
 
 .PHONY: xml
-xml: verify-virtualenv
+xml: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/xml
 	@echo
 	@echo "Build finished. The XML files are in $(BUILD_DOC_DIR)/xml."
 
 .PHONY: pseudoxml
-pseudoxml: verify-virtualenv
+pseudoxml: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILD_DOC_DIR)/pseudoxml."
 
 .PHONY: dummy
-dummy: verify-virtualenv
+dummy: regen-api-doc verify-virtualenv
 	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILD_DOC_DIR)/dummy
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
diff --git a/test/doc/framework.rst b/test/doc/framework.rst
deleted file mode 100644
index ce5e16e2eab..00000000000
--- a/test/doc/framework.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-framework module
-================
-
-.. automodule:: framework
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/hook.rst b/test/doc/hook.rst
deleted file mode 100644
index f856e51972b..00000000000
--- a/test/doc/hook.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-hook module
-===========
-
-.. automodule:: hook
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/index.rst b/test/doc/index.rst
index 323b608fdfb..8cbe961f887 100644
--- a/test/doc/index.rst
+++ b/test/doc/index.rst
@@ -22,7 +22,7 @@ Anatomy of a test case
 ######################
 
 Python's unittest_ is used as the base framework upon which the VPP test
-framework is built. A test suite in the |vtf| constists of multiple classes
+framework is built. A test suite in the |vtf| consists of multiple classes
 derived from `VppTestCase`, which is itself derived from TestCase_.
 The test class defines one or more test functions, which act as test cases.
 
@@ -44,11 +44,11 @@ Function flow when running a test case is:
    The tearDown function is called after each test function with the purpose
    of doing partial cleanup.
 5. `tearDownClass <VppTestCase.tearDownClass>`:
-   Method called once after running all of the test funnctions to perform
+   Method called once after running all of the test functions to perform
    the final cleanup.
 
 Test temporary directory and VPP life cycle
-################################################
+###########################################
 
 Test separation is achieved by separating the test files and vpp instances.
 Each test creates a temporary directory and it's name is used to create
@@ -60,7 +60,7 @@ are stored in this temporary test directory.
 Virtual environment
 ###################
 
-Virtualenv_ is a python module which provides a means to crate an environment
+Virtualenv_ is a python module which provides a means to create an environment
 containing the dependencies required by the |vtf|, allowing a separation
 from any existing system-wide packages. |vtf|'s Makefile automatically
 creates a virtualenv_ inside build-root and installs the required packages
@@ -72,7 +72,7 @@ Naming conventions
 
 Most unit tests do some kind of packet manipulation - sending and receiving
 packets between VPP and virtual hosts connected to the VPP. Referring
-to the sides, addresses, etc.. is always done as if looking from the VPP side,
+to the sides, addresses, etc. is always done as if looking from the VPP side,
 thus:
 
 * *local_* prefix is used for the VPP side.
diff --git a/test/doc/log.rst b/test/doc/log.rst
deleted file mode 100644
index 5965d5adff5..00000000000
--- a/test/doc/log.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-log module
-==========
-
-.. automodule:: log
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/modules.rst b/test/doc/modules.rst
deleted file mode 100644
index 773283e399a..00000000000
--- a/test/doc/modules.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-test
-====
-
-.. toctree::
-   :maxdepth: 4
-
-   framework
-   hook
-   log
-   run_tests
-   scapy_handlers
-   template_bd
-   test_ip4
-   test_ip6
-   test_l2bd
-   test_l2xc
-   test_lb
-   test_mpls
-   test_vxlan
-   util
-   vpp_interface
-   vpp_papi_provider
-   vpp_pg_interface
-   vpp_sub_interface
diff --git a/test/doc/run_tests.rst b/test/doc/run_tests.rst
deleted file mode 100644
index 30cec4e3055..00000000000
--- a/test/doc/run_tests.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-run_tests module
-================
-
-.. automodule:: run_tests
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/scapy_handlers.rst b/test/doc/scapy_handlers.rst
deleted file mode 100644
index 6717326a2fe..00000000000
--- a/test/doc/scapy_handlers.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-scapy_handlers package
-======================
-
-Submodules
-----------
-
-scapy_handlers.vxlan module
----------------------------
-
-.. automodule:: scapy_handlers.vxlan
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: scapy_handlers
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/template_bd.rst b/test/doc/template_bd.rst
deleted file mode 100644
index e173d27aaf6..00000000000
--- a/test/doc/template_bd.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-template_bd module
-==================
-
-.. automodule:: template_bd
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/test_ip4.rst b/test/doc/test_ip4.rst
deleted file mode 100644
index c3c3a23a8b8..00000000000
--- a/test/doc/test_ip4.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-test_ip module
-==============
-
-.. automodule:: test_ip4
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/test_ip6.rst b/test/doc/test_ip6.rst
deleted file mode 100644
index 63461c3cbe9..00000000000
--- a/test/doc/test_ip6.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-test_ip6 module
-===============
-
-.. automodule:: test_ip6
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/test_l2bd.rst b/test/doc/test_l2bd.rst
deleted file mode 100644
index 8a80dfe6a5b..00000000000
--- a/test/doc/test_l2bd.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-test_l2bd module
-================
-
-.. automodule:: test_l2bd
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/test_l2xc.rst b/test/doc/test_l2xc.rst
deleted file mode 100644
index caf99badf2d..00000000000
--- a/test/doc/test_l2xc.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-test_l2xc module
-================
-
-.. automodule:: test_l2xc
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/test_lb.rst b/test/doc/test_lb.rst
deleted file mode 100644
index e134b29c940..00000000000
--- a/test/doc/test_lb.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-test_lb module
-==============
-
-.. automodule:: test_lb
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/test_mpls.rst b/test/doc/test_mpls.rst
deleted file mode 100644
index e4c8ce0e718..00000000000
--- a/test/doc/test_mpls.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-test_mpls module
-================
-
-.. automodule:: test_mpls
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/test_vxlan.rst b/test/doc/test_vxlan.rst
deleted file mode 100644
index 7f40c319013..00000000000
--- a/test/doc/test_vxlan.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-test_vxlan module
-=================
-
-.. automodule:: test_vxlan
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/util.rst b/test/doc/util.rst
deleted file mode 100644
index d8ad0d148dc..00000000000
--- a/test/doc/util.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-util module
-===========
-
-.. automodule:: util
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/vpp_interface.rst b/test/doc/vpp_interface.rst
deleted file mode 100644
index 32bb009b6e4..00000000000
--- a/test/doc/vpp_interface.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-vpp_interface module
-====================
-
-.. automodule:: vpp_interface
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/vpp_papi_provider.rst b/test/doc/vpp_papi_provider.rst
deleted file mode 100644
index c9efe85a3c3..00000000000
--- a/test/doc/vpp_papi_provider.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-vpp_papi_provider module
-========================
-
-.. automodule:: vpp_papi_provider
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/vpp_pg_interface.rst b/test/doc/vpp_pg_interface.rst
deleted file mode 100644
index 85f54f625e5..00000000000
--- a/test/doc/vpp_pg_interface.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-vpp_pg_interface module
-=======================
-
-.. automodule:: vpp_pg_interface
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/test/doc/vpp_sub_interface.rst b/test/doc/vpp_sub_interface.rst
deleted file mode 100644
index 5ff5300b415..00000000000
--- a/test/doc/vpp_sub_interface.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-vpp_sub_interface module
-========================
-
-.. automodule:: vpp_sub_interface
-    :members:
-    :undoc-members:
-    :show-inheritance: