doc/CMakeLists.txt

##
## Licensed to the Apache Software Foundation (ASF) under one
## or more contributor license agreements.  See the NOTICE file
## distributed with this work for additional information
## regarding copyright ownership.  The ASF licenses this file
## to you under the Apache License, Version 2.0 (the
## "License"); you may not use this file except in compliance
## with the License.  You may obtain a copy of the License at
##
##   http://www.apache.org/licenses/LICENSE-2.0
##
## Unless required by applicable law or agreed to in writing,
## software distributed under the License is distributed on an
## "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
## KIND, either express or implied.  See the License for the
## specific language governing permissions and limitations
## under the License.
##

# In old cmake (< 2.8) documentation is built by "make all" so set BUILD_DOC OFF
# if you don't want that. For new cmake it is only built by "make doc"
option(BUILD_DOCS "Generate documentation with 'make doc'" ON)
option(DOC_VERBOSE "Verbose output from doc tools for debugging" OFF)
option(DOC_XMLLINT "Use xmllint to verify XML output" OFF)

if(BUILD_DOCS)
  if ("${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION}" VERSION_LESS "2.8")
    # OPTIONAL does not exist in install before 2.8 so always make and install docs
    set(DOC_TARGET ALL)
    macro(install_doc)
      install(${ARGN})
    endmacro()
  else()
    macro(install_doc)
      install(${ARGN} OPTIONAL)
    endmacro()
  endif()

  # Popular locations
  set(src ${CMAKE_CURRENT_SOURCE_DIR})
  set(bin ${CMAKE_CURRENT_BINARY_DIR})
  set(tools ${CMAKE_SOURCE_DIR}/tools)
  set(schema ../python/qpid_dispatch/management/qdrouter.json)
  set(py_management ../python/qpid_dispatch_internal/management)
  set(schema_depends ${schema} ${py_management}/schema_doc.py ${py_management}/schema.py)

  # Flags for doc tools, based on cmake options
  set(ADOC_FLAGS "--conf-file=${bin}/asciidoc.conf")
  set(A2X_FLAGS "--asciidoc-opts=--conf-file=${bin}/asciidoc.conf" -D${bin})
  if (DOC_VERBOSE)
    set(ADOC_FLAGS ${ADOC_FLAGS} -v)
    set(A2X_FLAGS ${A2X_FLAGS} -v)
  endif()
  if (NOT DOC_XMLLINT)
    set(A2X_FLAGS ${A2X_FLAGS} --no-xmllint)
  endif()

  # Generate asciidoc fragments from management schema to incorporate in text
  macro(schema_gen script output)
    add_custom_command(
      OUTPUT ${output}
      COMMAND ${RUN} -s ${script} 1> ${output}
      DEPENDS ${script} ${schema_depends})
    list(APPEND GENERATED_TXT "${output}")
  endmacro()

  schema_gen(${src}/book/schema_txt.py ${bin}/schema.adoc)
  schema_gen(${src}/man/qdrouterd.conf.5.py ${bin}/qdrouterd.conf.5.adoc)

  # Generate asciidoc .adoc from --help output for man pages
  macro(help2txt program)
    get_filename_component(name ${program} NAME)
    set(output ${bin}/${name}_help.adoc)
    add_custom_command(
      OUTPUT ${output}
      COMMAND ${RUN} -s ${src}/man/help2txt.py ${program} --help 1> ${output}
      DEPENDS ${program} ${schema_depends} ${src}/man/help2txt.py)
    list(APPEND GENERATED_TXT "${output}")
  endmacro()

  help2txt(${CMAKE_BINARY_DIR}/router/qdrouterd)
  help2txt(${tools}/qdmanage)
  help2txt(${tools}/qdstat)

  add_custom_target(doc_gen ALL DEPENDS ${GENERATED_TXT})
  install(DIRECTORY ${src}/book/ DESTINATION ${QD_DOC_INSTALL_DIR})
  install(FILES ${bin}/schema.adoc DESTINATION ${QD_DOC_INSTALL_DIR})

  find_program(ASCIIDOC_EXE asciidoc DOC "Generate HTML documentation")
  if (ASCIIDOC_EXE)
    configure_file(${src}/asciidoc.conf.in ${bin}/asciidoc.conf)

    # Copy the book dir images for HTML viewing in the build directory.
    # Don't use configure_file since it truncates .png files at 1st ^Z character
    EXECUTE_PROCESS(COMMAND ${CMAKE_COMMAND} -E copy_directory ${src}/book/ ${bin})

    # Generate HTML
    file(GLOB_RECURSE ADOC_SRC *.adoc)
    foreach(source index book/book man/qdmanage.8 man/qdrouterd.8 man/qdstat.8 ${bin}/qdrouterd.conf.5)
      get_filename_component(name ${source} NAME)
      set(output ${bin}/${name}.html)
      add_custom_command(
        OUTPUT ${output} ${output}.in
        # Pretty .html for direct viewing.
        COMMAND ${ASCIIDOC_EXE} ${ADOC_FLAGS} -o ${output} ${source}.adoc
        # Raw .html.in body for inclusion in Qpid website.
        COMMAND  ${ASCIIDOC_EXE} ${ADOC_FLAGS} -s -o ${output}.in ${source}.adoc
        DEPENDS ${source}.adoc ${GENERATED_TXT} ${ADOC_SRC} ${bin}/asciidoc.conf
        WORKING_DIRECTORY ${src} # Book include links assume we are in source dir.
        )
      list(APPEND DOC_DEPENDS ${output})
      install_doc(FILES ${output} DESTINATION ${QD_DOC_INSTALL_DIR})
    endforeach()

    find_program(A2X_EXE a2x DOC DOC "Generate Unix man pages")
    if (A2X_EXE)
      # Generate man pages.
      foreach(source ${src}/man/qdmanage.8 ${src}/man/qdrouterd.8 ${src}/man/qdstat.8 ${bin}/qdrouterd.conf.5)
        get_filename_component(name ${source} NAME)
        string(REGEX MATCH "\\.([0-9])$" section ${source}) # Man section number
        set(output ${bin}/${name})
        add_custom_command(
          OUTPUT ${output}
          COMMAND ${A2X_EXE} ${A2X_FLAGS} -f manpage -D ${bin} ${source}.adoc
          DEPENDS ${source}.adoc ${GENERATED_TXT})
        list(APPEND DOC_DEPENDS ${output})
        install_doc(FILES ${output} DESTINATION ${CMAKE_INSTALL_PREFIX}/${MAN_INSTALL_DIR}/man${section})
      endforeach()

      # Generate PDF if we have the latex tool
      find_program(DBLATEX_EXE dblatex "Generate PDF documentation")
      if (DBLATEX_EXE)
        add_custom_command(
          OUTPUT ${bin}/book.pdf
          COMMAND ${A2X_EXE} ${A2X_FLAGS} -f pdf ${src}/book/book.adoc
          DEPENDS ${src}/book/book.adoc ${GENERATED_TXT})
        list(APPEND DOC_DEPENDS ${bin}/book.pdf)
        install_doc(FILES ${bin}/book.pdf DESTINATION ${QD_DOC_INSTALL_DIR})
      else(DBLATEX_EXE)
        message(STATUS "dblatex not found: not generating PDF")
      endif(DBLATEX_EXE)
    else(A2X_EXE)
      message(STATUS "a2x not found: not generating man pages or PDF")
    endif(A2X_EXE)
  else(ASCIIDOC_EXE)
    message(STATUS "asciidoc not found: not generating HTML, man pages or PDF")
  endif(ASCIIDOC_EXE)

  add_custom_target(doc ${DOC_TARGET} DEPENDS ${DOC_DEPENDS})
endif(BUILD_DOCS)