From 16ed15ee5ffc3c4ed5d4aa214df657d18683622d Mon Sep 17 00:00:00 2001 From: Matt Williams Date: Thu, 1 Jul 2010 12:57:37 +0000 Subject: [PATCH] qcollectiongenerator (comes with Qt Assistant) is now also required for building the documentation. This allows us to open the Doxygen-generated docs in Qt Assistant and have them fully searchable. This should all work on Windows too as long as Doxygen is installed. See the changes to INSTALL.txt for details of the change. --- CMakeLists.txt | 9 ++++++++- INSTALL.txt | 11 +++++++++-- library/CMakeLists.txt | 10 +++++++--- library/Doxyfile.in | 7 ++++--- library/polyvox.qhcp.in | 20 ++++++++++++++++++++ 5 files changed, 48 insertions(+), 9 deletions(-) create mode 100644 library/polyvox.qhcp.in 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 + + +