Change cmake files to make documentation optional (#2)

* CHAM-613 - Add cmake options for building and downloading docs

Signed-off-by: Patrick Masselink <patrick.masselink@adlinktech.com>

src/CMakeLists.txt

@@ -70,8 +70,15 @@ add_subdirectory(util)
 add_subdirectory(core)
 add_subdirectory(tools)
 add_subdirectory(scripts)
-#add_subdirectory(examples)
+
-#add_subdirectory(docs)
+option(USE_DOCS "Enable documentation." OFF)
+if(USE_DOCS)
+    add_subdirectory(docs)
+else()
+    message(STATUS "${CMAKE_PROJECT_NAME} documentation: disabled (-DUSE_DOCS=1 to enable)")
+endif()
+
+add_subdirectory(examples)
 
 # Pull-in CPack and support for generating <Package>Config.cmake and packages.
 include(Packaging)

src/docs/CMakeLists.txt

@@ -8,50 +8,101 @@
 # http://www.eclipse.org/org/documents/edl-v10.php.
 #
 # SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
-#
+
 # TODO depending on requirements we can add/remove options as needed,
 # these are examples of generators we'll need as a minimum.
 # Perhaps we should also consider options for building subset of all docs.
 # When a certain doc is related to a target, no option is needed; you can simply check if the target exists
 # (i.e. if a target 'ddsc' exists, build ddsc api docs). And possibly make the target definition dependent on an option.
 
-option(BUILD_DOCS, "Enable generation of docs." OFF)
+option(BUILD_DOCS "Build documentation." OFF)
-# Above option should only be set when building master on a designated Jenkins job; every other
+option(DOWNLOAD_DOCS "Download documentation." OFF)
-# Jenkins job/development machine can download them from there.
-
-set(JENKINS_BASE_URI "http://jenkins.prismtech.com:8080/")
-set(JENKINS_DOCS_JOB_NAME "BuildChameleonLinux64bit")
-set(PROJECT_PDF_URI "${JENKINS_BASE_URI}/job/${JENKINS_DOCS_JOB_NAME}/lastSuccessfulBuild/artifact/cham/builds/${CMAKE_PROJECT_NAME}.pdf")
-set(PROJECT_HTML_URI "${JENKINS_BASE_URI}/job/${JENKINS_DOCS_JOB_NAME}/lastSuccessfulBuild/artifact/cham/builds/${CMAKE_PROJECT_NAME}HTML.tar.gz")
-set(DOCS_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/..")
 
+# When BUILD_DOCS is set, missing deps are treated as fatal errors
 if (BUILD_DOCS)
+    set(mode FATAL_ERROR)
+else()
+    set(mode STATUS)
+endif()
+
 find_program(SPHINX_EXECUTABLE NAMES sphinx-build DOC "Sphinx documentation builder")
 if (NOT SPHINX_EXECUTABLE)
-    set(BUILD_DOCS off)
+    message(${mode} "${CMAKE_PROJECT_NAME} documentation: unable to find sphinx-build executable")
-    message("-- Unable to find sphinx-build executable -> download documentation")
-  endif()
 endif()
 
-if (BUILD_DOCS)
 find_package(Doxygen)
 if (NOT Doxygen_FOUND)
-    set(BUILD_DOCS off)
+    message(${mode} "${CMAKE_PROJECT_NAME} documentation: unable to find Doxygen")
-    message("-- Unable to find Doxygen -> download documentation")
-  endif()
 endif()
 
-if (BUILD_DOCS)
 # Creating pdf from latex requires latexmk (which depends on perl, latexpdf et. al)
 find_program(LATEXMK_EXECUTABLE NAMES latexmk DOC "LateX PDF Generator")
 if (NOT LATEXMK_EXECUTABLE)
-    set(BUILD_DOCS off)
+    message(${mode} "${CMAKE_PROJECT_NAME} documentation: unable to find latexmk")
-    message("-- Unable to find latexmk executable -> download documentation")
-  endif()
 endif()
 
-if (BUILD_DOCS)
+if ((NOT DOWNLOAD_DOCS) AND SPHINX_EXECUTABLE AND Doxygen_FOUND AND LATEXMK_EXECUTABLE)
-  # Generate ddsc API docs in XML format using Doxygen
+    # User requested docs (USE_DOCS=1) and did not explicitely request to download docs (DOWNLOAD_DOCS=0)
+    # All prerequisites are available to build docs, so force BUILD_DOCS even when the user did not enable it explicitely
+    set(BUILD_DOCS ON PARENT_SCOPE) # for examples' docs
+    set(BUILD_DOCS ON)
+    message(STATUS "${CMAKE_PROJECT_NAME} documentation: Success (build)")
+else()
+    # User requested docs (USE_DOCS=1) and prefers to download instead of build (or prerequisites are not available).
+    # So force DOWNLOAD_DOCS even when user did not enable it explicitely
+    set(DOWNLOAD_DOCS ON PARENT_SCOPE) # for examples' docs
+    set(DOWNLOAD_DOCS ON)
+    message(STATUS "${CMAKE_PROJECT_NAME} documentation: Success (download)")
+endif()
+
+#set(DOCS_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/..")
+
+if (DOWNLOAD_DOCS)
+    set(JENKINS_BASE_URI "http://jenkins.prismtech.com:8080/")
+    set(JENKINS_DOCS_JOB_NAME "BuildChameleonLinux64bit")
+    set(PROJECT_PDF_URI "${JENKINS_BASE_URI}/job/${JENKINS_DOCS_JOB_NAME}/lastSuccessfulBuild/artifact/cham/builds/docs/${CMAKE_PROJECT_NAME}.pdf")
+    set(PROJECT_HTML_URI "${JENKINS_BASE_URI}/job/${JENKINS_DOCS_JOB_NAME}/lastSuccessfulBuild/artifact/cham/builds/docs/${CMAKE_PROJECT_NAME}HTML.tar.gz")
+
+    add_custom_target(docs ALL)
+    find_program(WGET_EXECUTABLE NAMES wget DOC "wget")
+    if (WGET_EXECUTABLE)
+        # prevent wget to create numbered downloads.
+        add_custom_command(TARGET docs
+            COMMAND ${CMAKE_COMMAND}
+              -E remove -f "${CMAKE_PROJECT_NAME}HTML.tar.gz"
+            VERBATIM)
+
+        add_custom_command(TARGET docs
+            COMMAND ${WGET_EXECUTABLE}
+              -q ${PROJECT_HTML_URI} ${PROJECT_PDF_URI}
+            COMMENT "Downloading documentation from target."
+            VERBATIM)
+
+        # To make downloading and packaging easier.
+#        add_custom_command(TARGET docs
+#            COMMAND ${CMAKE_COMMAND}
+#              -E rename ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}.pdf ${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}.pdf
+#            VERBATIM)
+    else()
+        message(STATUS "Unable to find wget. Download docs now.")
+        # Just try to download the docs straight away.
+        file(DOWNLOAD ${PROJECT_HTML_URI} ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}HTML.tar.gz)
+        file(DOWNLOAD ${PROJECT_PDF_URI} ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}.pdf)
+    endif()
+
+    add_custom_command(TARGET docs
+        COMMAND ${CMAKE_COMMAND}
+          -E tar "zxf" "${CMAKE_PROJECT_NAME}HTML.tar.gz" .
+        VERBATIM)
+
+    # Remove downloaded files when cleaning the build tree
+    set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES
+        html
+        ${CMAKE_PROJECT_NAME}HTML.tar.gz
+        ${CMAKE_PROJECT_NAME}.pdf)
+
+elseif(BUILD_DOCS)
+    # Generate ddsc API docs in XML format using Doxygen, if the ddsc target is defined.
     # The XML will serve as input for sphinx' breathe plugin
     if (TARGET ${CMAKE_PROJECT_NAME}::ddsc)
         # Process doxygen configuration file, for ddsc
@@ -73,13 +124,10 @@ if (BUILD_DOCS)
         # Add ddsc api docs to sphinx' breathe projects
         set(sph_conf_breathe_projs "\"ddsc_api\": \"${doxy_conf_outputdir}/xml\"")
 
-    add_custom_command(
+        add_custom_command(TARGET ddsc_docs
-      TARGET ddsc_docs
             POST_BUILD
             WORKING_DIRECTORY "${doxy_conf_outputdir}"
-      COMMAND ${CMAKE_COMMAND}
+            COMMAND ${CMAKE_COMMAND} -E tar "zcf" "${CMAKE_PROJECT_NAME}_C_HTML.tar.gz" "ddsc")
-        -E tar "zcf" "${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}_C_HTML.tar.gz" "ddsc"
-    )
     endif()
 
     # Process sphinx configuration file
@@ -102,124 +150,71 @@ if (BUILD_DOCS)
         # Log stdout (not stderr) to a file instead of messing up build output
         set(docs_builder_log "sphinx-build-${builder}.log")
 
-    add_custom_command(
+        add_custom_command(OUTPUT ${docs_builder_output}
-      OUTPUT ${docs_builder_output}
             COMMAND ${SPHINX_EXECUTABLE}
               -b ${builder}
               -d ${CMAKE_CURRENT_BINARY_DIR}/cache
               -c ${CMAKE_CURRENT_BINARY_DIR}
               ${PROJECT_SOURCE_DIR}/docs
-        ${CMAKE_CURRENT_BINARY_DIR}/${builder}
+              ${CMAKE_CURRENT_BINARY_DIR}/${builder} > ${docs_builder_log}
-        > ${docs_builder_log}
             COMMENT "Running Sphinx for ${builder} output"
-      VERBATIM
+            VERBATIM)
-    )
 
         # FIXME: This is definitely in the wrong location
         if(builder STREQUAL html)
-      add_custom_command(
+            add_custom_command(OUTPUT ${docs_builder_output}
-        OUTPUT ${docs_builder_output}
                 COMMAND ${CMAKE_COMMAND}
                   -E tar "zcf"
-          "${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}HTML.tar.gz"
+                  "${CMAKE_PROJECT_NAME}HTML.tar.gz"
-          "${CMAKE_CURRENT_BINARY_DIR}/html"
+                  "html"
                 APPEND
-        VERBATIM
+                VERBATIM)
-      )
         endif()
 
         # Create a pdf from the latex builder output, by appending a latexmk command
         # TODO look into rinohtype as an alternative (don't bother with rst2pdf, it's no good)
         if(builder STREQUAL latex)
-      add_custom_command(
+            add_custom_command(OUTPUT ${docs_builder_output}
-        OUTPUT ${docs_builder_output}
                 COMMAND ${LATEXMK_EXECUTABLE}
                   -interaction=nonstopmode
                   -silent
                   -output-directory=${builder}
                   -pdf -dvi- -ps- -cd- ${builder}/${CMAKE_PROJECT_NAME}.tex
                 APPEND
-        VERBATIM
+                VERBATIM)
-      )
+
-      add_custom_command(
+            # Move the pdf, so that install rules don't need to differentiate between built and downloaded docs
-        OUTPUT ${docs_builder_output}
+            add_custom_command(OUTPUT ${docs_builder_output}
                 COMMAND ${CMAKE_COMMAND}
                   -E rename
-            ${CMAKE_CURRENT_BINARY_DIR}/latex/${CMAKE_PROJECT_NAME}.pdf
+                  "latex/${CMAKE_PROJECT_NAME}.pdf"
-            ${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}.pdf
+                  "${CMAKE_PROJECT_NAME}.pdf"
                 APPEND
-        VERBATIM
+                VERBATIM)
-      )
         endif()
 
         # OUTPUT is a fake target / symbolic name, not an actual file
         set_property(SOURCE ${docs_builder_output} PROPERTY SYMBOLIC 1)
         # Remove generated files when cleaning the build tree
-    set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${builder} ${docs_builder_log})
+        set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES
+            ${builder}
+            ${docs_builder_log})
+
         # Include this builder as a dependency of the general 'docs' target
         list(APPEND docs_outputs ${docs_builder_output})
     endforeach()
 
     # Remove generated files when cleaning the build tree
-  set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}HTML.tar.gz ${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}.pdf)
+    set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES
+        ${CMAKE_PROJECT_NAME}HTML.tar.gz
+        ${CMAKE_PROJECT_NAME}.pdf)
 
     add_custom_target(docs ALL DEPENDS ddsc_docs ${docs_outputs})
-else()
-  add_custom_target(docs ALL)
-  find_program(WGET_EXECUTABLE NAMES wget DOC "wget")
-  if (WGET_EXECUTABLE)
-    # prevent wget to create numbered downloads.
-    add_custom_command(
-      TARGET docs
-      COMMAND ${CMAKE_COMMAND}
-        -E remove -f "${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}HTML.tar.gz"
-      VERBATIM
-    )
-    add_custom_command(
-      TARGET docs
-      COMMAND ${WGET_EXECUTABLE}
-        -q
-        ${PROJECT_HTML_URI}
-        ${PROJECT_PDF_URI}
-      COMMENT "Downloading documentation from target."
-      VERBATIM
-    )
-    # To make downloading and packaging easier.
-    add_custom_command(
-      TARGET docs
-      COMMAND ${CMAKE_COMMAND}
-        -E rename
-          ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}.pdf
-          ${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}.pdf
-      VERBATIM
-    )
-  else()
-    message("-- Unable to find wget. Download docs now.")
-    # Just try to download the docs straight away.
-    file(DOWNLOAD
-      ${PROJECT_HTML_URI}
-      ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}HTML.tar.gz)
-    file(DOWNLOAD
-      ${PROJECT_PDF_URI}
-      ${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}.pdf)
 endif()
 
-  add_custom_command(
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
-    TARGET docs
-    COMMAND ${CMAKE_COMMAND}
-      -E tar "zxf" "${CMAKE_PROJECT_NAME}HTML.tar.gz" .
-    VERBATIM
-  )
-  # Remove generated files when cleaning the build tree
-  set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES html ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}HTML.tar.gz ${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}.pdf)
-
-endif()
-
-install(
-  DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
     DESTINATION ${CMAKE_INSTALL_DOCDIR}
     COMPONENT dev)
-install(
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}.pdf
-  FILES ${DOCS_OUTPUT_DIR}/${CMAKE_PROJECT_NAME}.pdf
     DESTINATION ${CMAKE_INSTALL_DOCDIR}
     COMPONENT dev)

src/examples/CMakeLists.txt

@@ -15,21 +15,29 @@ add_subdirectory(helloworld)
 add_subdirectory(roundtrip)
 add_subdirectory(throughput)
 
-# Examples HTML documentation
+if (USE_DOCS)
+    # TODO Move to docs CMakeLists
     set(EXAMPLES_HTML_ARCHIVE "${CMAKE_PROJECT_NAME}ExamplesHTML.tar.gz")
+    if (DOWNLOAD_DOCS)
+        message(STATUS "${CMAKE_PROJECT_NAME} Examples documentation: Success (download)")
         set(EXAMPLES_HTML_URI "http://jenkins.prismtech.com:8080/job/BuildChameleonLinux64bit/lastSuccessfulBuild/artifact/cham/builds/examples/${EXAMPLES_HTML_ARCHIVE}")
-
+        file(DOWNLOAD "${EXAMPLES_HTML_URI}" "${CMAKE_CURRENT_BINARY_DIR}/Downloaded${EXAMPLES_HTML_ARCHIVE}"
-if (BUILD_DOCS)
+            TIMEOUT 10
-  find_program(SPHINX_EXECUTABLE NAMES sphinx-build DOC "Sphinx documentation builder")
+            STATUS status)
-  if (NOT SPHINX_EXECUTABLE)
+        list(GET status 0 status_code)
-    message(STATUS "Unable to find sphinx-build executable, downloading examples docs...")
+        list(GET status 1 status_string)
-    set(BUILD_DOCS off)
+        if (NOT status_code EQUAL 0)
-  endif()
+            message(FATAL_ERROR
+                "Failed to download ${EXAMPLES_HTML_URI} (Code: ${status_code}, ${status_string})")
         endif()
 
-if (BUILD_DOCS)
+        add_custom_target(examples_docs ALL)
-    message(STATUS "Examples html docs will be built using sphinx (${SPHINX_EXECUTABLE})")
+        add_custom_command(TARGET examples_docs
+            COMMAND ${CMAKE_COMMAND} -E tar "zxf" "Downloaded${EXAMPLES_HTML_ARCHIVE}"
+            VERBATIM)
 
+    elseif (BUILD_DOCS)
+        message(STATUS "${CMAKE_PROJECT_NAME} Examples documentation: Success (build)")
         # Process sphinx configuration file
         set(sph_conf_author "ADLINK")
         string(TIMESTAMP sph_conf_copyright "%Y, ADLINK")
@@ -39,18 +47,15 @@ if (BUILD_DOCS)
 
         set(builder_output "examples_html_output")
         set(builder_log "sphinx-examples-html.log")
-    add_custom_command(
+        add_custom_command(OUTPUT ${builder_output}
-      OUTPUT ${builder_output}
             COMMAND ${SPHINX_EXECUTABLE}
               -b html
               -d ${CMAKE_CURRENT_BINARY_DIR}/cache
               -c ${CMAKE_CURRENT_BINARY_DIR}
               ${CMAKE_CURRENT_SOURCE_DIR}
-        ${CMAKE_CURRENT_BINARY_DIR}
+              ${CMAKE_CURRENT_BINARY_DIR} > ${builder_log}
-        > ${builder_log}
             COMMENT "Running Sphinx for examples html output"
-      VERBATIM
+            VERBATIM)
-    )
 
         # OUTPUT is a fake target / symbolic name, not an actual file
         set_property(SOURCE ${builder_output} PROPERTY SYMBOLIC 1)
@@ -66,51 +71,25 @@ if (BUILD_DOCS)
             "examples.html"
             "helloworld/readme.html"
             "roundtrip/readme.html"
-        "throughput/readme.html"
+            "throughput/readme.html")
-    )
+
-    add_custom_command(
+        add_custom_command(OUTPUT ${builder_output}
-      OUTPUT ${builder_output}
             COMMAND ${CMAKE_COMMAND}
               -E tar "zcf"
               "${EXAMPLES_HTML_ARCHIVE}"
               ${html_outputs}
             APPEND
-      VERBATIM
+            VERBATIM)
-    )
 
         # Remove generated files when cleaning the build tree
-    set_property(
+        set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES
-        DIRECTORY
-        APPEND PROPERTY
-        ADDITIONAL_MAKE_CLEAN_FILES
             "cache"
             "${builder_log}"
             "objects.inv"
             ${html_outputs}
             "_sources"
-            "${EXAMPLES_HTML_ARCHIVE}"
+            "${EXAMPLES_HTML_ARCHIVE}")
-    )
-else()
-    # Download example html docs
-
-    file(DOWNLOAD "${EXAMPLES_HTML_URI}" "${CMAKE_CURRENT_BINARY_DIR}/Downloaded${EXAMPLES_HTML_ARCHIVE}"
-        TIMEOUT 10
-        STATUS status
-    )
-    list(GET status 0 status_code)
-    list(GET status 1 status_string)
-    if (NOT status_code EQUAL 0)
-        message(FATAL_ERROR
-            "Failed to download ${EXAMPLES_HTML_URI} \
-            (Code: ${status_code}, ${status_string})"
-        )
     endif()
-
-    add_custom_target(examples_docs ALL)
-    add_custom_command(TARGET examples_docs
-        COMMAND ${CMAKE_COMMAND} -E tar "zxf" "Downloaded${EXAMPLES_HTML_ARCHIVE}"
-        VERBATIM
-    )
 endif()
 
 if(CMAKE_SYSTEM_NAME MATCHES "Windows")