Doxygen system added to DGtaltools

.travis.yml

@@ -3,15 +3,27 @@ language: cpp
 
 sudo: false
 
+os:
+  - linux
 
 compiler:
   - gcc
   - clang
 
 
 env:
-  - DGTALTYPE="-DBUILD_EXAMPLES=OFF -DDGTAL_BUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Debug -DWITH_QGLVIEWER=true -DWITH_ITK=false"
-  - DGTALTYPE="-DBUILD_EXAMPLES=OFF -DDGTAL_BUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Debug -DWITH_QGLVIEWER=false -DWITH_ITK=false"
+  - CONFIG="Debug,QGLVIEWER"
+  - CONFIG="Debug"
+  - CONFIG="DOCUMENTATION"
+
+matrix:
+  fast_finish: true
+  exclude:
+    - os: osx
+      env: CONFIG="DOCUMENTATION"
+    - compiler: gcc
+      os: linux
+      env: CONFIG="DOCUMENTATION"
 
 addons:
   apt:
@@ -35,6 +47,9 @@ addons:
 
 
 before_install:
+  - DOC="false"
+  - if [ $CONFIG == "DOCUMENTATION" ]; then if [ $OriginalRepo == "true" ];  then if [ $TRAVIS_PULL_REQUEST == "false" ]; then DOC="true"; fi; fi; fi
+  - if [ $DOC == true ];then   openssl aes-256-cbc -K $encrypted_a0b8e3011fca_key -iv $encrypted_a0b8e3011fca_iv -in .travis/dgtal_rsa.enc -out .travis/dgtal_rsa -d ; fi
   - env
   - export SRC_DIR="`pwd`"
   - if [ $CXX == "g++" ]; then export CXX="g++-4.8"  CC="gcc-4.8" BOOST_TOOLSET=gcc CCOMPILER="gcc-4.8" CXXCOMPILER="g++-4.8"; fi
@@ -49,6 +64,8 @@ before_install:
   - if [ ! -f "$BOOST_ROOT/b2" ]; then cd "$BOOST_ROOT"; ./bootstrap.sh --with-toolset="$BOOST_TOOLSET" --with-libraries=program_options; fi
 
 before_script:
+  - DGTALTYPE="-DBUILD_EXAMPLES=OFF -DDGTAL_BUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Debug -DWITH_QGLVIEWER=false -DWITH_ITK=false"
+  - if [ $CONFIG="Debug,QGLVIEWER"]; then DGTALTYPE="-DBUILD_EXAMPLES=OFF -DDGTAL_BUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Debug -DWITH_QGLVIEWER=false -DWITH_ITK=false"; fi
   - ccache -V && ccache --show-stats && ccache --zero-stats
   - 'echo "using gcc : : ccache $CXX : <cflags>-std=c11 <cxxflags>-std=c++11 ;" > ~/user-config.jam'
   - 'echo "using clang : : ccache $CXX : <cflags>-std=c11 <cxxflags>-std=c++11 ;" >> ~/user-config.jam'
@@ -59,7 +76,10 @@ before_script:
   - cmake . $DGTALTYPE -DCMAKE_CXX_COMPILER=$CXXCOMPILER -DCMAKE_C_COMPILER=$CCOMPILER -DBOOST_ROOT=$BOOST_ROOT
   - make
   - cd ..
+  - if [ $DOC == "true" ]; then .travis/install_doxygen.sh;  BTYPE="-DDOXYGEN_EXECUTABLE=$HOME/doxygen/doxygen-1.8.10/bin/doxygen -DCMAKE_BUILD_TYPE=Debug -DWITH_CAIRO=true  -DWITH_GMP=true"; DOC="true"; fi
 
 script:
    - cmake . -DDGtal_DIR=$PWD/DGtal -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=$CXXCOMPILER -DCMAKE_C_COMPILER=$CCOMPILER -DBOOST_ROOT=$BOOST_ROOT
-   - make
+   - if [ $DOC == "true" ]; then  make doc;  rsync -azv --delete --delete-after -e 'ssh -oStrictHostKeyChecking=no -i  .travis/dgtal_rsa' html/ dgtal@liris.cnrs.fr:/home/dgtal/public_html/doc/tools/nightly/;  fi
+   - if [ $CONFIG == "Debug"]; then make; fi
+   - if [ $CONFIG == "Debug,QGLVIEWER"]; then make; fi

.travis/install_doxygen.sh

@@ -0,0 +1,4 @@
+
+mkdir ~/doxygen && cd ~/doxygen
+wget http://ftp.stack.nl/pub/users/dimitri/doxygen-1.8.10.linux.bin.tar.gz
+tar xzf doxygen-1.8.10.linux.bin.tar.gz

CMakeLists.txt

@@ -4,28 +4,34 @@
 # -----------------------------------------------------------------------------
 PROJECT(DGtalTools)
 
-cmake_minimum_required (VERSION 2.6) 
+cmake_minimum_required (VERSION 2.6)
 
+SET(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${PROJECT_SOURCE_DIR}/cmake")
 
+
+# -----------------------------------------------------------------------------
+# DGtal dependencies
+# -----------------------------------------------------------------------------
+message(STATUS "-------------------------------------------------------------------------------")
+message(STATUS "Checking if DGtal is installed:")
 FIND_PACKAGE(DGtal 0.9.1 REQUIRED)
 INCLUDE_DIRECTORIES(${DGTAL_INCLUDE_DIRS})
 LINK_DIRECTORIES(${DGTAL_LIBRARY_DIRS})
-
-
 SET(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
+message(STATUS "DGtal found.")
 
- # -------------------------------------------------------------------------
- # This test is for instance used for ITK v3.x. ITK forces a limited
- # template depth. We remove this option.
- # --------------------------------------------------------------------------
- if (CMAKE_CXX_FLAGS MATCHES "-ftemplate-depth-[0-9]*")
+# -------------------------------------------------------------------------
+# This test is for instance used for ITK v3.x. ITK forces a limited
+# template depth. We remove this option.
+# --------------------------------------------------------------------------
+if (CMAKE_CXX_FLAGS MATCHES "-ftemplate-depth-[0-9]*")
     message( "Warning: some package has enabled a limited template depth for the C++ compiler." )
     message( "         Disabling option -ftemplate-depth-xx in CMAKE_CXX_FLAGS." )
     set( CMAKE_CXX_FLAGS_TMP ${CMAKE_CXX_FLAGS} )
     STRING( REGEX REPLACE "-ftemplate-depth-[0-9]*" ""
     CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS_TMP}" )
      message ("         CMAKE_CXX_FLAGS=" ${CMAKE_CXX_FLAGS} )
-  endif (CMAKE_CXX_FLAGS MATCHES "-ftemplate-depth-[0-9]*")
+endif (CMAKE_CXX_FLAGS MATCHES "-ftemplate-depth-[0-9]*")
 
 
 
@@ -49,12 +55,25 @@ FIND_PACKAGE(Boost 1.46.0 REQUIRED COMPONENTS program_options)
 if ( Boost_FOUND )
   message(STATUS "Boost and boost_program_options found.")
   include_directories( ${Boost_INCLUDE_DIRS} )
-  SET(DGtalToolsLibDependencies ${DGtalToolsLibDependencies} 
-     ${Boost_LIBRAIRIES}  
+  SET(DGtalToolsLibDependencies ${DGtalToolsLibDependencies}
+     ${Boost_LIBRAIRIES}
      ${Boost_PROGRAM_OPTIONS_LIBRARY})
    SET(DGtalLibInc ${Boost_INCLUDE_DIRS})
 endif( Boost_FOUND )
 
+
+
+
+# -----------------------------------------------------------------------------
+# Documentation
+# -----------------------------------------------------------------------------
+message(STATUS "-------------------------------------------------------------------------------")
+message(STATUS "Checking if doxygen/dot is installed:")
+set(INSTALL_DOC_PATH ${CMAKE_INSTALL_PREFIX}/share/DGtalTools CACHE PATH "Installation directory for DGtal documentation files.")
+INCLUDE(doxygen)
+INCLUDE(TargetDoxygenDoc OPTIONAL)
+message(STATUS "-------------------------------------------------------------------------------")
+
 #------Tools subdirectories ------
 add_subdirectory(volumetric)
 add_subdirectory(shapeGenerator)

cmake/TargetDoxygenDoc.cmake

@@ -0,0 +1,104 @@
+FIND_PACKAGE(Doxygen)
+
+IF (DOXYGEN_FOUND)
+
+  # click+jump in Emacs and Visual Studio (for doxy.config) (jw)
+  IF    (CMAKE_BUILD_TOOL MATCHES "(msdev|devenv)")
+    SET(DOXY_WARN_FORMAT "\"$file($line) : $text \"")
+  ELSE  (CMAKE_BUILD_TOOL MATCHES "(msdev|devenv)")
+    SET(DOXY_WARN_FORMAT "\"$file:$line: $text \"")
+  ENDIF (CMAKE_BUILD_TOOL MATCHES "(msdev|devenv)")
+
+  # we need latex for doxygen because of the formulas
+  FIND_PACKAGE(LATEX)
+  IF    (NOT LATEX_COMPILER)
+    MESSAGE(STATUS "latex command LATEX_COMPILER not found but usually required. You will probably get warnings and user interaction on doxy run.")
+  ENDIF (NOT LATEX_COMPILER)
+  IF    (NOT MAKEINDEX_COMPILER)
+    MESSAGE(STATUS "makeindex command MAKEINDEX_COMPILER not found but usually required.")
+  ENDIF (NOT MAKEINDEX_COMPILER)
+  IF    (NOT DVIPS_CONVERTER)
+    MESSAGE(STATUS "dvips command DVIPS_CONVERTER not found but usually required.")
+  ENDIF (NOT DVIPS_CONVERTER)
+
+  IF   (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config.in")
+    MESSAGE(STATUS "configured ${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config.in --> ${CMAKE_CURRENT_BINARY_DIR}/doxy.config")
+    CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config.in
+      ${CMAKE_CURRENT_BINARY_DIR}/doxy.config
+      @ONLY )
+    # use (configured) doxy.config from (out of place) BUILD tree:
+    SET(DOXY_CONFIG "${CMAKE_CURRENT_BINARY_DIR}/doxy.config")
+  ELSE (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config.in")
+    # use static hand-edited doxy.config from SOURCE tree:
+    SET(DOXY_CONFIG "${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config")
+    IF   (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config")
+      MESSAGE(STATUS "WARNING: using existing ${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config instead of configuring from doxy.config.in file.")
+    ELSE (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config")
+      IF   (EXISTS "${CMAKE_MODULE_PATH}/doc/doxy.config.in")
+        # using template doxy.config.in
+        MESSAGE(STATUS "configured ${CMAKE_CMAKE_MODULE_PATH}/doc/doxy.config.in --> ${CMAKE_CURRENT_BINARY_DIR}/doc/doxy.config")
+        CONFIGURE_FILE(${CMAKE_MODULE_PATH}/doc/doxy.config.in
+          ${CMAKE_CURRENT_BINARY_DIR}/doxy.config
+          @ONLY )
+        SET(DOXY_CONFIG "${CMAKE_CURRENT_BINARY_DIR}/doxy.config")
+      ELSE (EXISTS "${CMAKE_MODULE_PATH}/doc/doxy.config.in")
+        # failed completely...
+        MESSAGE(SEND_ERROR "Please create ${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config.in (or doxy.config as fallback)")
+      ENDIF(EXISTS "${CMAKE_MODULE_PATH}/doc/doxy.config.in")
+
+    ENDIF(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config")
+  ENDIF(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doc/doxy.config.in")
+
+
+  ADD_CUSTOM_TARGET(doc ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG})
+
+#  ADD_CUSTOM_TARGET(doc)
+
+  # create a windows help .chm file using hhc.exe
+  # HTMLHelp DLL must be in path!
+  # fallback: use hhw.exe interactively
+  IF    (WIN32)
+    FIND_PACKAGE(HTMLHelp)
+    IF   (HTML_HELP_COMPILER)
+      SET (TMP "${CMAKE_CURRENT_BINARY_DIR}\\Doc\\html\\index.hhp")
+      STRING(REGEX REPLACE "[/]" "\\\\" HHP_FILE ${TMP} )
+      # MESSAGE(SEND_ERROR "DBG  HHP_FILE=${HHP_FILE}")
+      ADD_CUSTOM_TARGET(winhelp ${HTML_HELP_COMPILER} ${HHP_FILE})
+      ADD_DEPENDENCIES (winhelp doc)
+
+      IF (NOT TARGET_DOC_SKIP_INSTALL)
+      # install windows help?
+      # determine useful name for output file
+      # should be project and version unique to allow installing
+      # multiple projects into one global directory
+      IF   (EXISTS "${PROJECT_BINARY_DIR}/Doc/html/index.chm")
+        IF   (PROJECT_NAME)
+          SET(OUT "${PROJECT_NAME}")
+        ELSE (PROJECT_NAME)
+          SET(OUT "Documentation") # default
+        ENDIF(PROJECT_NAME)
+        IF   (${PROJECT_NAME}_VERSION_MAJOR)
+          SET(OUT "${OUT}-${${PROJECT_NAME}_VERSION_MAJOR}")
+          IF   (${PROJECT_NAME}_VERSION_MINOR)
+            SET(OUT  "${OUT}.${${PROJECT_NAME}_VERSION_MINOR}")
+            IF   (${PROJECT_NAME}_VERSION_PATCH)
+              SET(OUT "${OUT}.${${PROJECT_NAME}_VERSION_PATCH}")
+            ENDIF(${PROJECT_NAME}_VERSION_PATCH)
+          ENDIF(${PROJECT_NAME}_VERSION_MINOR)
+        ENDIF(${PROJECT_NAME}_VERSION_MAJOR)
+        # keep suffix
+        SET(OUT  "${OUT}.chm")
+
+        #MESSAGE("DBG ${PROJECT_BINARY_DIR}/Doc/html/index.chm \n${OUT}")
+        # create target used by install and package commands
+        INSTALL(FILES "${PROJECT_BINARY_DIR}/Doc/html/index.chm"
+          DESTINATION "doc"
+          RENAME "${OUT}"
+        )
+      ENDIF(EXISTS "${PROJECT_BINARY_DIR}/Doc/html/index.chm")
+      ENDIF(NOT TARGET_DOC_SKIP_INSTALL)
+
+    ENDIF(HTML_HELP_COMPILER)
+    # MESSAGE(SEND_ERROR "HTML_HELP_COMPILER=${HTML_HELP_COMPILER}")
+  ENDIF (WIN32)
+ENDIF(DOXYGEN_FOUND)

cmake/doxygen.cmake

@@ -0,0 +1,22 @@
+# Generate doc only if Doxygen is present.
+set( PACKAGE ${PROJECT_NAME} )
+set( VERSION ${PROJECT_VERSION} )
+set( DOC_DIR ${PROJECT_SOURCE_DIR}/doc )
+set( top_srcdir ${PROJECT_SOURCE_DIR} )
+set( top_bindir ${PROJECT_BINARY_DIR} )
+set( HAVE_DOT YES )
+find_program(DOT_EXE dot)
+if ( DOT_EXE )
+  message (STATUS "dot found: ${DOT_EXE}. Installing doc in ${INSTALL_DOC_PATH}")
+else ( DOT_EXE )
+  message( WARNING "Note: dot program not found in environment. If you wish to use it in doxygen, you should add its path to the variable PATH." )
+  message( STATUS "disabling dot." )
+  set( HAVE_DOT NO )
+endif ( DOT_EXE )
+if (NOT EXISTS ${PROJECT_SOURCE_DIR}/doc/html)
+  file(MAKE_DIRECTORY ${PROJECT_SOURCE_DIR}/doc/html)
+endif (NOT EXISTS ${PROJECT_SOURCE_DIR}/doc/html)
+
+## Installation target
+install(DIRECTORY ${PROJECT_SOURCE_DIR}/doc/html DESTINATION ${INSTALL_DOC_PATH})
+

converters/HDF52vol.cpp

@@ -43,6 +43,29 @@ using namespace Z3i;
 
 namespace po = boost::program_options;
 
+/**
+ @page HDF52vol HDF52vol
+ @brief Converts a 3D 8-bit HDF5 file to vol.
+
+@b Usage: HDF52vol [input] [output]
+
+@b Allowed @b options @b are:
+
+@code
+  -h [ --help ]                     display this message
+  -i [ --input ] arg                the input FreemanChain file name
+  -o [ --output ] arg (=result.pgm)  the output filename
+@endcode
+
+@b Example:
+@code
+  $HDF52vol -i ${DGtal}/tests/samples/ex_image2.h5 -o out.vol
+@endcode
+
+@see HDF52vol.cpp
+
+*/
+
 
 /**
  * Missing parameter error message.

converters/convertVol.cpp

@@ -42,6 +42,31 @@
 using namespace std;
 using namespace DGtal;
 
+/**
+ @page convertVol convertVol
+ @brief Converts volumetric file into volumetric file from different formats (pgm3d, vol, longvol).
+
+
+@b Usage: convertVol [input] [output]
+
+@b Allowed @b options @b are:
+
+@code
+  -h [ --help ]         display this message
+  -i [ --input ] arg    volumetric file (.pgm3d, .vol, .longvol) 
+  -o [ --output ] arg   volumetric file (.pgm3d, .vol, .longvol) 
+@endcode
+
+@b Example:
+@code 
+$ convertVol -i ${DGtal}/examples/samples/lobster.vol -o convertedVol.p3d 
+@endcode
+
+
+@see convertVol.cpp
+
+*/
+
 
 ///////////////////////////////////////////////////////////////////////////////
 namespace po = boost::program_options;
@@ -70,7 +95,7 @@ int main( int argc, char** argv )
   if( !parseOK || vm.count("help")||argc<=1)
     {
       std::cout << "Usage: " << argv[0] << " [input] [output]\n"
-		<< "Convert volumetric  file into volumetric file from different formats (pgm3d, vol, longvol) "
+		<< "Convert volumetric file into volumetric file from different formats (pgm3d, vol, longvol) "
 		<< general_opt << "\n";
       std::cout << "Example:\n"
 		<< "convertVol -i ${DGtal}/examples/samples/lobster.vol -o convertedVol.p3d \n";

converters/dicom2vol.cpp

@@ -44,6 +44,32 @@ using namespace std;
 using namespace DGtal;
 
 
+/**
+ @page dicom2vol dicom2vol
+ @brief Converts dicom file into a volumetric file (.vol, .longvol .pgm3d).
+
+@b Usage: dicom2vol [input] [output]
+
+@b Allowed @b options @b are:
+
+@code
+  -h [ --help ]           display this message
+  -i [ --input ] arg      dicom image  (.dcm) 
+  -o [ --output ] arg     volumetric file (.vol, .longvol .pgm3d) 
+  --dicomMin arg (=-1000) set minimum density threshold on Hounsfield scale
+  --dicomMax arg (=3000)  set maximum density threshold on Hounsfield scale
+@endcode
+
+@b Example:
+@code  
+$ dicom2vol -i ${DGtal}/tests/samples/dicomSample/1629.dcm --dicomMin -500 --dicomMax -100 -o sample.vol
+@endcode
+
+@see dicom2vol.cpp
+
+*/
+
+
 ///////////////////////////////////////////////////////////////////////////////
 namespace po = boost::program_options;