Docs reorganization and update

Docs reorganization and update using the latest afb-test improvments and
try to make it clearer.

Change-Id: If022cdb46364ef250361bdcd420d45b360f10a2e
Signed-off-by: Romain Forlot <romain.forlot@iot.bzh>
(cherry picked from commit 2f3654275e44f9719818a848da9a0b576d5a1b53)

1 files changed, 97 insertions, 0 deletions

diff --git a/docs/2_The_test_widget.md b/docs/2_The_test_widget.md
new file mode 100644
index 0000000..afd4c6d
--- /dev/null
+++ b/docs/2_The_test_widget.md
@@ -0,0 +1,97 @@
+# How to build the test widget using app-templates/cmake-apps-module
+
+## Defining CMake targets
+
+Now that the test tree has been created, in each directory you have to create
+a `CMakeLists.txt` file to hold the CMake's target definition. For each target
+you need to specify a **LABELS** depending on the purpose of the files for each
+directory. There are more explanations about using the *cmake-apps-module* (the
+former *app-templates* submodule) in the [documentation website](2_4-Use-app-templates.html#using-cmake-template-macros).
+
+Here is a cheat sheet to map the **LABELS** target for each classic test tree
+directory:
+
+* `etc` uses the label **TEST-CONFIG**
+* `fixtures` uses the label **TEST-DATA**
+* `tests` uses the label **TEST-DATA**
+
+i.e the `etc` folder:
+
+```cmake
+PROJECT_TARGET_ADD(test-config)
+
+    file(GLOB CONF_FILES "*.json")
+
+    add_input_files("${CONF_FILES}")
+
+    SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
+        LABELS "TEST-CONFIG"
+        OUTPUT_NAME ${TARGET_NAME}
+    )
+```
+
+i.e the `fixtures` folder:
+
+```cmake
+PROJECT_TARGET_ADD(test-fixtures)
+
+    # Change the glob pattern to match your file's type
+    file(GLOB DATA_FILES "*.sh" "*.data")
+
+    add_input_files("${DATA_FILES}")
+
+    SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
+        LABELS "TEST-DATA"
+        OUTPUT_NAME ${TARGET_NAME}
+    )
+```
+
+i.e the `tests` folder:
+
+
+```cmake
+PROJECT_TARGET_ADD(tests)
+
+    file(GLOB CONF_FILES "*.lua")
+
+    add_input_files("${CONF_FILES}")
+
+    SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
+        LABELS "TEST-DATA"
+        OUTPUT_NAME ${TARGET_NAME}
+    )
+```
+
+> **CAUTION**: make sure that you have CMakeLists files that include your
+> subdirectories target (cf: previous chapter `Write the tests`).
+
+## Build the test widget
+
+By default, the test widget is not built, you have to specify that you want to
+build it or use a special target.
+
+### Building at the same time than classic widget
+
+Specify the option `BUILD_TEST_WGT=TRUE` when you configure your build.
+
+ie:
+
+```bash
+cd build
+cmake -DBUILD_TEST_WIDGET=TRUE ..
+make
+make widget
+```
+
+### Building separately only the test widget
+
+Just use the target `test_widget` after a classic build.
+
+ie:
+
+```bash
+cd build
+cmake ..
+make
+make test_widget
+```