Update doc & use gitbook to enhance doc generation

Change-Id: If42c916f7664ea67b818a21b8f50c66c41e11f89
Signed-off-by: Romain Forlot <romain.forlot@iot.bzh>

1 files changed, 92 insertions, 0 deletions

diff --git a/docs/dev_guide/3_advanced_usage.md b/docs/dev_guide/3_advanced_usage.md
new file mode 100644
index 0000000..8994b41
--- /dev/null
+++ b/docs/dev_guide/3_advanced_usage.md
@@ -0,0 +1,92 @@
+# Build a widget
+
+## config.xml.in file
+
+To build a widget you need a _config.xml_ file describing what is your apps and
+how Application Framework would launch it. This repo provide a simple default
+file _config.xml.in_ that should work for simple application without
+interactions with others bindings.
+
+It is recommanded that you use the sample one which is more complete. You can
+find it at the same location under the name _config.xml.in.sample_ (stunning
+isn't it). Just copy the sample file to your _conf.d/wgt_ directory and name it
+_config.xml.in_, then edit it to fit your needs.
+
+> ***CAUTION*** : The default file is only meant to be use for a
+> simple widget app, more complicated ones which needed to export
+> their api, or ship several app in one widget need to use the provided
+> _config.xml.in.sample_ which had all new Application Framework
+> features explained and examples.
+
+## Using cmake template macros
+
+To leverage all cmake templates features, you have to specify ***properties***
+on your targets. Some macros will not works without specifying which is the
+target type.
+
+As the type is not always specified for some custom targets, like an ***HTML5***
+application, macros make the difference using ***LABELS*** property.
+
+Choose between:
+
+- **BINDING**: Shared library that be loaded by the AGL Application Framework
+- **HTDOCS**: Root directory of a web app
+- **DATA**: Resources used by your application
+- **EXECUTABLE**: Entry point of your application executed by the AGL
+ Application Framework
+
+Example:
+
+```cmake
+SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
+		LABELS "HTDOCS"
+		OUTPUT_NAME dist.prod
+	)
+```
+
+If your target output is not named as the ***TARGET_NAME***, you need to specify
+***OUTPUT_NAME*** property that will be used by the ***populate_widget*** macro.
+
+Use the ***populate_widget*** macro as latest statement of your target
+definition. Then at the end of your project definition you should use the macro
+***build_widget*** that make an archive from the populated widget tree using the
+`wgtpkg-pack` Application Framework tools.
+
+## Macro reference
+
+### PROJECT_TARGET_ADD
+
+Typical usage would be to add the target to your project using macro
+`PROJECT_TARGET_ADD` with the name of your target as parameter.
+
+Example:
+
+```cmake
+PROJECT_TARGET_ADD(low-can-demo)
+```
+
+> ***NOTE***: This will make available the variable `${TARGET_NAME}`
+> set with the specificied name. This variable will change at the next call
+> to this macros.
+
+### project_subdirs_add
+
+This macro will search in all subfolder any `CMakeLists.txt` file. If found then
+it will be added to your project. This could be use in an hybrid application by
+example where the binding lay in a sub directory.
+
+Usage :
+
+```cmake
+project_subdirs_add()
+```
+
+You also can specify a globbing pattern as argument to filter which folders
+will be looked for.
+
+To filter all directories that begin with a number followed by a dash the
+anything:
+
+```cmake
+project_subdirs_add("[0-9]-*")
+```