Enable doxygen been properly used from cmake build and install.

Current documentation lacks a proper directory handling and switch for
Unix like systems.
The option BUILD_DOCS are added as disable by default, even so the
Doxyfile file is generated for a manual build.

Option HTML_OUTPUT are made cached to be properly replaced, as usually
done by some Linux distributions

Microsoft CHM option is enabled if MSVC is detected.

CMakeLists.txt

@@ -79,6 +79,12 @@ OPTION ( ASSIMP_COVERALLS
    OFF
 )
 
+OPTION ( BUILD_DOCS
+   "Build documentation using Doxygen."
+   OFF
+)
+add_subdirectory(doc)
+
 IF(MSVC)
   set (CMAKE_PREFIX_PATH "D:\\libs\\devil")
   OPTION( ASSIMP_INSTALL_PDB
@@ -160,6 +166,10 @@ IF( UNIX )
   ENDIF()
 ENDIF()
 
+IF( UNIX )
+    include(GNUInstallDirs)
+ENDIF( UNIX )
+
 IF((CMAKE_COMPILER_IS_GNUCC OR CMAKE_COMPILER_IS_GNUCXX) AND NOT CMAKE_COMPILER_IS_MINGW)
   IF (BUILD_SHARED_LIBS AND CMAKE_SIZEOF_VOID_P EQUAL 8) # -fPIC is only required for shared libs on 64 bit
      SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC")

doc/CMakeLists.txt

@@ -0,0 +1,47 @@
+# Only test for Doxygent if BUILD_DOCS are ON
+# We will configure Doxygen output anyway in case
+# of manual generation
+if( BUILD_DOCS )
+    find_package( Doxygen REQUIRED )
+endif( BUILD_DOCS )
+
+set( HTML_OUTPUT "AssimpDoc_Html" CACHE STRING "Output directory for generated HTML documentation. Defaults to AssimpDoc_Html." )
+
+# Enable Microsoft CHM help style only on Windows
+set( MICROSOFT_HELP_WORKSHOP "NO")
+if( MSVC )
+    set( MICROSOFT_HELP_WORKSHOP "YES" )
+endif( MSVC )
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+    ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+    @ONLY
+)
+
+add_custom_target( 
+    docs ALL
+    DEPENDS docs.done
+)
+
+add_custom_command(
+    OUTPUT docs.done
+    COMMAND ${DOXYGEN_EXECUTABLE}
+    COMMAND ${CMAKE_COMMAND} -E touch docs.done
+    COMMENT "Generating assimp documentation"
+    VERBATIM
+    )
+
+if( DEFINED CMAKE_INSTALL_DOCDIR )
+    install(
+        DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${HTML_OUTPUT}
+        DESTINATION ${CMAKE_INSTALL_DOCDIR}/assimp-${PROJECT_VERSION}
+    )
+    install(FILES
+        ${CMAKE_CURRENT_SOURCE_DIR}/AssimpDoc_Html/AnimationOverview.png
+        ${CMAKE_CURRENT_SOURCE_DIR}/AssimpDoc_Html/AnimationOverview.svg
+        ${CMAKE_CURRENT_SOURCE_DIR}/AssimpDoc_Html/dragonsplash.png
+        DESTINATION ${CMAKE_INSTALL_DOCDIR}/assimp-${PROJECT_VERSION}
+    )
+endif( DEFINED CMAKE_INSTALL_DOCDIR )
+

doc/Doxyfile → doc/Doxyfile.in

@@ -140,7 +140,8 @@ FULL_PATH_NAMES        = NO
 # relative paths, which will be relative from the directory where doxygen is 
 # started.
 
-STRIP_FROM_PATH        = 
+STRIP_FROM_PATH        = @PROJECT_SOURCE_DIR@ \
+                         @PROJECT_BINARY_DIR@
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of 
 # the path mentioned in the documentation of a class, which tells 
@@ -339,22 +340,6 @@ INLINE_SIMPLE_STRUCTS  = NO
 
 TYPEDEF_HIDES_STRUCT   = YES
 
-# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to 
-# determine which symbols to keep in memory and which to flush to disk. 
-# When the cache is full, less often used symbols will be written to disk. 
-# For small to medium size projects (<1000 input files) the default value is 
-# probably good enough. For larger projects a too small cache size can cause 
-# doxygen to be busy swapping symbols to and from disk most of the time 
-# causing a significant performance penalty. 
-# If the system has enough physical memory increasing the cache will improve the 
-# performance by keeping more symbols in memory. Note that the value works on 
-# a logarithmic scale so increasing the size by one will roughly double the 
-# memory usage. The cache size is given by this formula: 
-# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, 
-# corresponding to a cache size of 2^16 = 65536 symbols.
-
-SYMBOL_CACHE_SIZE      = 0
-
 # Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be 
 # set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given 
 # their name and scope. Since this can be an expensive process and often the 
@@ -677,9 +662,12 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ../include/ \
-                         ../doc/dox.h \
-                         ../code/BaseImporter.h
+INPUT                  = @doxy_main_page@ \
+                         @PROJECT_SOURCE_DIR@ \
+                         @PROJECT_BINARY_DIR@ \
+                         @PROJECT_SOURCE_DIR@/include/ \
+                         @PROJECT_SOURCE_DIR@/doc/dox.h \
+                         @PROJECT_SOURCE_DIR@/code/BaseImporter.h
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -919,7 +907,7 @@ GENERATE_HTML          = YES
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be 
 # put in front of it. If left blank `html' will be used as the default path.
 
-HTML_OUTPUT            = AssimpDoc_Html
+HTML_OUTPUT            = @HTML_OUTPUT@
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for 
 # each generated HTML page (for example: .htm,.php,.asp). If it is left blank 
@@ -953,7 +941,7 @@ HTML_FOOTER            =
 # HTML_EXTRA_STYLESHEET instead of this one, as it is more robust and this 
 # tag will in the future become obsolete.
 
-HTML_STYLESHEET        = style.css
+# HTML_STYLESHEET        =  @CMAKE_CURRENT_SOURCE_DIR@/style.css
 
 # The HTML_EXTRA_STYLESHEET tag can be used to specify an additional 
 # user-defined cascading style sheet that is included after the standard 
@@ -1064,7 +1052,7 @@ DOCSET_PUBLISHER_NAME  = Publisher
 # Microsoft HTML help workshop to generate a compiled HTML help file (.chm) 
 # of the generated HTML documentation.
 
-GENERATE_HTMLHELP      = YES
+GENERATE_HTMLHELP      = @MICROSOFT_HELP_WORKSHOP@
 
 # If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can 
 # be used to specify the file name of the resulting .chm file. You 
@@ -1504,18 +1492,6 @@ GENERATE_XML           = NO
 
 XML_OUTPUT             = xml
 
-# The XML_SCHEMA tag can be used to specify an XML schema, 
-# which can be used by a validating XML parser to check the 
-# syntax of the XML files.
-
-XML_SCHEMA             = 
-
-# The XML_DTD tag can be used to specify an XML DTD, 
-# which can be used by a validating XML parser to check the 
-# syntax of the XML files.
-
-XML_DTD                = 
-
 # If the XML_PROGRAMLISTING tag is set to YES Doxygen will 
 # dump the program listings (including syntax highlighting 
 # and cross-referencing information) to the XML output. Note that