DOC: enhance documentation about the template module

CMakeLists.txt

-cmake_minimum_required(VERSION 2.8.9)
+cmake_minimum_required(VERSION 3.10.2)
 project(ExternalTemplate)
 
+# This module create a library, with the same name as the module
 set(ExternalTemplate_LIBRARIES ExternalTemplate)
 
 if(NOT OTB_SOURCE_DIR)
+  # Handle the compilation outside OTB source tree: find where OTB is built/installed
   find_package(OTB REQUIRED)
   list(APPEND CMAKE_MODULE_PATH ${OTB_CMAKE_DIR})
   include(UseOTB)
+
+  # The Python interpreter is needed for Python tests
   set(Python_ADDITIONAL_VERSIONS "3")
   find_package( PythonInterp REQUIRED)
+
+  # This script will process the module sources
   include(OTBModuleExternal)
 else()
   otb_module_impl()

README.md

@@ -3,15 +3,17 @@
 [![Build Status](https://travis-ci.org/orfeotoolbox/remote-module-template.svg?branch=master)](https://travis-ci.org/orfeotoolbox/remote-module-template)
 
 This is a template module for the ORFEO
-Toolbox(https://www.orfeo-toolbox.org/). It is designed to work with OTBv5
-modular system and to be places in OTB/Module/Remote.
+Toolbox(https://www.orfeo-toolbox.org/). It is designed to work with OTB >= 5.0
+modular system. The module can be clone/copied in `OTB/Module/Remote` and
+compiled along with other OTB modules. However, it is also possible to build it
+as a standalone module.
 
-This module is empty it is just a template to be used as a starting point for a
-module with actual content. It contains the template for:
+This module is filled with a few templates to be used as a starting point for a
+module with actual content. It contains the templates for:
 
-* sources (`src` folder)
-* includes and templated classes (`include` folder)
-* application (`app` folder)
+* a library (`cxx` source in `src` folder)
+* headers and templated classes (`include` folder)
+* a OTB Application (`app` folder)
 * tests for C++ sources, applications and python wrappers (`test` folder)
 
 This module also has its own continuous integration scripts (using Travis CI).
@@ -38,7 +40,7 @@ otb_fetch_module(ExternalTemplate
 
 ### Editing
 
-The CMakeLists.txt and otb-modules need to be modified with the name of the
+The files `CMakeLists.txt` and `otb-module.cmake` need to be modified with the name of the
 module, something along the following:
 
 ```
@@ -50,14 +52,37 @@ hand or look up the option in sed.
 
 Then hack away at you code in include, src, test and app folders.
 
+### Continuous Integration
+
+This module contains default files to enable Continuous Integration on
+Travis-CI:
+
+* `travis-ci.yml` : this is the backbone of the CI process in Travis-CI, it
+  defines the different jobs to run, and their environment
+* `ci.cmake` : this CTest script drives the build and test process.
+* `vcvars_proxy.py` : this script is used on Windows to export variables from
+  `vcvarsall.bat` to the Git-Bash executor.
+
+The `README.md` starts with a Travis-CI badge, you can change it to match your
+own module.
+
+If you need to access data file from `OTB/Data`, you can tune the file
+`ci.cmake` which will download them for you before building:
+
+* `RM_GET_FULL_DATA`: this flag will download all files under `OTB/Data`
+* `RM_DATA_PATTERNS`: this variable allows to download only the files you need.
+  Set this variable to a list of patterns (for instance
+  `Data/Input/QB_Toulouse_*.tif`). This method should be faster.
+
 ### License
 
 This software is distributed under the Apache License. Please see LICENSE for
 details.
 
-### Author
+### Authors
 
 Manuel Grizonnet
+Guillaume Pasero
 
 ### Thanks
 

app/CMakeLists.txt

+
+# This macro creates the application EmptyApp. It must be linked to
+# OTBApplicationEngine. Since the module has its own library,
+# the variable ${otb-module}_LIBRARIES only contains this library, which doesn't
+# drag OTBApplicationEngine, so we need to add it explicitely.
 OTB_CREATE_APPLICATION(NAME EmptyApp
                        SOURCES otbEmptyApp.cxx
                        LINK_LIBRARIES ${${otb-module}_LIBRARIES} ${OTBApplicationEngine_LIBRARIES}
 )
-
-
-
-
-

include/otbSomeFile.h

 #ifndef otbSomeFile_h
 #define otbSomeFile_h
 
+// this header defines export macros, such as ExternalTemplate_EXPORT.
+// On Windows, it is replaced by declspec import/export
 #include "ExternalTemplateExport.h"
 
 namespace otb {

otb-module.cmake

 set(DOCUMENTATION "OTB module template.")
 
-# OTB_module() defines the module dependencies in ExternalTemplate
-# ExternalTemplate depends on OTBCommon and OTBApplicationEngine
-# The testing module in ExternalTemplate depends on OTBTestKernel
-# and OTBCommandLine
+# otb_module() defines the module dependencies of ExternalTemplate.
+# ExternalTemplate depends on:
+#   - OTBCommon (base dependency of all modules)
+#   - OTBApplicationEngine (because we build an application in the module, see 'app' folder)
+# 
+# The tests of module ExternalTemplate drag additional dependencies:
+#   - OTBTestKernel (needed for any test driver)
+#   - OTBCommandLine (needed to run tests on applications)
+#   - OTBSWIG (needed to run tests with Python bindings)
+#
+# The option ENABLE_SHARED is needed because this module creates a shared
+# library. It generates a header with usefull export macros
+# (ExternalTemplateExport.h), so that other binaries can link to this library.
 
-# define the dependencies of the include module and the tests
 otb_module(ExternalTemplate
   ENABLE_SHARED
   DEPENDS
@@ -14,6 +22,7 @@ otb_module(ExternalTemplate
   TEST_DEPENDS
     OTBTestKernel
     OTBCommandLine
+    OTBSWIG
   DESCRIPTION
     "${DOCUMENTATION}"
 )

src/CMakeLists.txt

-#${otb-module} will be the name of this module and will not need to be
-#changed when this module is renamed.
+# ${otb-module} will be the name of this module, and also the name of its
+# library. It will not need to be changed when this module is renamed.
 
 set(${otb-module}_SRC
 otbSomeFile.cxx

test/CMakeLists.txt

@@ -20,7 +20,7 @@ otb_test_application(NAME otbEmptyAppTest
                      APP  EmptyApp
                      )
 
-# Test a Python script using OTB Applications
+# Test a Python script using OTB Applications bindings.
 set(TEST_DRIVER otbTestDriver
     --add-before-env OTB_APPLICATION_PATH $<TARGET_FILE_DIR:otbapp_EmptyApp> )