diff --git a/CMakeLists.txt b/CMakeLists.txt index 75ec8146..b306170c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -40,6 +40,13 @@ IF(BUILD_TESTING) ADD_SUBDIRECTORY(tests) ENDIF(BUILD_TESTING) +#Check if we will be making the 'doc' target available +IF(DOXYGEN_FOUND AND QT_QCOLLECTIONGENERATOR_EXECUTABLE) + SET(BUILD_DOCS YES) +ELSE() + SET(BUILD_DOCS NO) +ENDIF() + # Option summary MESSAGE(STATUS "") @@ -47,5 +54,5 @@ MESSAGE(STATUS "Summary") MESSAGE(STATUS "-------") MESSAGE(STATUS "Build examples: " ${ENABLE_EXAMPLES}) MESSAGE(STATUS "Build tests: " ${BUILD_TESTING}) -MESSAGE(STATUS "API Docs available: " ${DOXYGEN_FOUND}) +MESSAGE(STATUS "API Docs available: " ${BUILD_DOCS}) MESSAGE(STATUS "") diff --git a/INSTALL.txt b/INSTALL.txt index 068a823b..0c0d0f4d 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -13,6 +13,7 @@ To build PolyVox you need: With the following options: * `Qt `_ for building the tests + * ``qcollectiongenerator`` which comes with Qt Assistant is required for bundling the docs for installation * `Doxygen `_ for building the documentation Linux @@ -77,11 +78,17 @@ To run the tests you do not need to have run ``make install``. Simply run:: API Documentation ----------------- -If you want to generate the API documentation, you'll need Doxygen installed. If you saw ``API Docs available: YES`` at the end of the CMake output then you're all set. To generate the docs, just run:: +If you want to generate the API documentation, you'll need Doxygen and ``qcollectiongenerator`` installed. If you saw ``API Docs available: YES`` at the end of the CMake output then you're all set. To generate the docs, just run:: make doc -and the documentation can be browsed from ``{build directory}/library/doc/html/index.html``. +and the documentation can be browsed in plain HTML form at ``/library/doc/html/index.html``. + +On top of this, PolyVox will also compile and install this documentation as a *Qt Help Collection* file to ``/share/doc/packages/polyvox/qthelp/polyvox.qhc`` (this file is in the build directory as ``/library/doc/html/polyvox.qhc``). To view this file you need Qt Assistant installed. You can open it with:: + + assistant -collectionFile library/doc/html/polyvox.qhc + +This allows indexed searching of the documentation and easier browsing. Windows ======= diff --git a/library/CMakeLists.txt b/library/CMakeLists.txt index 08ebd9f3..8ead8ed5 100644 --- a/library/CMakeLists.txt +++ b/library/CMakeLists.txt @@ -5,29 +5,33 @@ PROJECT(PolyVox) add_subdirectory(PolyVoxCore) add_subdirectory(PolyVoxUtil) -#Set up PolyVoxConfig.cmake +#Set up install paths e.g. for PolyVoxConfig.cmake if(WIN32) set(CONFIG_FILE_DIR "CMake") set(PolyVoxCore_LIBRARY_INSTALL_DIRS "PolyVoxCore/lib") set(PolyVoxUtil_LIBRARY_INSTALL_DIRS "PolyVoxUtil/lib") set(PolyVoxCore_INCLUDE_INSTALL_DIRS "PolyVoxCore/include") set(PolyVoxUtil_INCLUDE_INSTALL_DIRS "PolyVoxUtil/include") + set(PolyVox_DOC_INSTALL_DIR "PolyVox/doc") else(WIN32) set(CONFIG_FILE_DIR "share/PolyVox/cmake") set(PolyVoxCore_LIBRARY_INSTALL_DIRS "lib") set(PolyVoxUtil_LIBRARY_INSTALL_DIRS "lib") set(PolyVoxCore_INCLUDE_INSTALL_DIRS "include/PolyVoxCore") set(PolyVoxUtil_INCLUDE_INSTALL_DIRS "include/PolyVoxUtil") + set(PolyVox_DOC_INSTALL_DIR "share/doc/packages/polyvox") endif(WIN32) configure_file(${CMAKE_CURRENT_SOURCE_DIR}/PolyVoxConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/PolyVoxConfig.cmake @ONLY) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/PolyVoxConfig.cmake DESTINATION ${CONFIG_FILE_DIR} COMPONENT development) -if(DOXYGEN_FOUND) +if(DOXYGEN_FOUND AND QT_QCOLLECTIONGENERATOR_EXECUTABLE) #configure_file(${CMAKE_CURRENT_SOURCE_DIR}/polyvox.css ${CMAKE_CURRENT_BINARY_DIR}/polyvox.css) configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) - add_custom_target(doc COMMAND ${DOXYGEN_EXECUTABLE} WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Building documentation" VERBATIM) + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/polyvox.qhcp.in ${CMAKE_CURRENT_BINARY_DIR}/doc/html/polyvox.qhcp) + add_custom_target(doc COMMAND ${DOXYGEN_EXECUTABLE} COMMAND ${QT_QCOLLECTIONGENERATOR_EXECUTABLE} doc/html/polyvox.qhcp -o doc/html/polyvox.qhc WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Building documentation" VERBATIM) set_target_properties(doc PROPERTIES PROJECT_LABEL "Documentation") #Set label seen in IDE + install(FILES ${CMAKE_CURRENT_BINARY_DIR}/doc/html/polyvox.qhc ${CMAKE_CURRENT_BINARY_DIR}/doc/html/polyvox.qch DESTINATION ${PolyVox_DOC_INSTALL_DIR}/qthelp COMPONENT development) endif() #add_subdirectory(bindings) diff --git a/library/Doxyfile.in b/library/Doxyfile.in index 0635bd97..834ebacf 100644 --- a/library/Doxyfile.in +++ b/library/Doxyfile.in @@ -934,7 +934,8 @@ GENERATE_QHP = YES # be used to specify the file name of the resulting .qch file. # The path specified is relative to the HTML output folder. -QCH_FILE = polyvox.qch +#Comment this out since qcollectiongenerator handles this now +#QCH_FILE = polyvox.qch # The QHP_NAMESPACE tag specifies the namespace to use when generating # Qt Help Project output. For more information please see @@ -953,8 +954,8 @@ QHP_VIRTUAL_FOLDER = doc # If non-empty doxygen will try to run qhelpgenerator on the generated # .qhp file . -#TODO set by CMake -QHG_LOCATION = /usr/bin/qhelpgenerator +#Set this to empty so that we can leave the compilation to qcollectiongenerator +QHG_LOCATION = # The DISABLE_INDEX tag can be used to turn on/off the condensed index at # top of each HTML page. The value NO (the default) enables the index and diff --git a/library/polyvox.qhcp.in b/library/polyvox.qhcp.in new file mode 100644 index 00000000..d01cc3dc --- /dev/null +++ b/library/polyvox.qhcp.in @@ -0,0 +1,20 @@ + + + + PolyVox Documentation + qthelp://org.thermite3d.polyvox/doc/index.html + qthelp://org.thermite3d.polyvox/doc/index.html + false + + + + + index.qhp + polyvox.qch + + + + polyvox.qch + + +