From e4f05064dfdede57097d4e60a0733345a325cb77 Mon Sep 17 00:00:00 2001 From: Helio Chissini de Castro Date: Tue, 18 Apr 2017 14:51:17 +0200 Subject: [PATCH] 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 | 10 ++++++++ doc/CMakeLists.txt | 47 +++++++++++++++++++++++++++++++++++ doc/{Doxyfile => Doxyfile.in} | 46 ++++++++-------------------------- 3 files changed, 68 insertions(+), 35 deletions(-) create mode 100644 doc/CMakeLists.txt rename doc/{Doxyfile => Doxyfile.in} (98%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 9e7e07b47..f6ce4334c 100644 --- a/CMakeLists.txt +++ b/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") diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 000000000..0ad04cf33 --- /dev/null +++ b/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 ) + diff --git a/doc/Doxyfile b/doc/Doxyfile.in similarity index 98% rename from doc/Doxyfile rename to doc/Doxyfile.in index 64dd5d2cc..ebb6b72b8 100644 --- a/doc/Doxyfile +++ b/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