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 recent versions of cmake the documentation is not built automatically, you need to
# run "make doc", so you can leave this ON. In older (< 2.8) versions, documentation
# is built by "make all" so you need to turn BUILD_DOCS OFF if you don't want that.
option(BUILD_DOCS "Generate documentation" ON)

if(BUILD_DOCS)

  set(src ${CMAKE_CURRENT_SOURCE_DIR})
  set(bin ${CMAKE_CURRENT_BINARY_DIR})
  set(tools ${CMAKE_SOURCE_DIR}/tools)

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

  find_package(Doxygen)
  find_program(SPHINX_BUILD sphinx-build)

  # Create an option to enable/disable a doc tool and check if the tool is present.
  # If tool is present, option defaults to ON else OFF.
  # If option is set ON by user and tool is not present, that is an error.
  # If tool is not present and option is not set on just issue a status message.
  #
  macro(doc_tool tool use var what)
    if(${var})
      option(${use} "Generate ${what} with ${tool}" ON)
    else(${var})
      option(${use} "Generate ${what} with ${tool}" OFF)
      if(${use})
        message(SEND_ERROR "${use} enabled but ${tool} not found.")
      else(${use})
        message(STATUS "${tool} not found, not generating ${what}.")
      endif(${use})
    endif(${var})
  endmacro()

  doc_tool(sphinx-build USE_SPHINX SPHINX_BUILD "HTML and man page documentation")
  doc_tool(doxygen USE_DOXYGEN DOXYGEN_FOUND "API documentation")
  doc_tool(dot USE_DOT DOT "diagrams in API documentation (also requires doxygen)")

  # Copy configuration and rst sources to build directory to generate book.
  # Use configure_file to ensure we re-copy if the source changes.
  configure_file(${src}/conf.py.in ${bin}/conf.py)
  configure_file(${src}/man/qdmanage.rst.in ${bin}/man/qdmanage.rst)
  configure_file(${src}/man/qdrouterd.rst.in ${bin}/man/qdrouterd.rst)
  file(GLOB_RECURSE RST_SRC RELATIVE ${src} *.rst)
  foreach(file ${RST_SRC})
    configure_file(${src}/${file} ${bin}/${file} COPYONLY)
  endforeach()

  # Generate files from management schema
  set(schema, "${CMAKE_SOURCE_DIR}/python/qpid_router/management/qdrouterd.json")
  set(py_management ${CMAKE_SOURCE_DIR}/python/qpid_dispatch_internal/management)
  set(schema_gen_deps ${py_management}/schema_doc.py ${py_management}/schema.py ${schema})

  macro(schema_gen output script)
    add_custom_command(
      OUTPUT ${output}
      COMMAND ${RUN} -s ${script} 1> ${output}
      DEPENDS ${script} ${schema_gen_deps}
      )
    list(APPEND SCHEMA_GEN ${output})
  endmacro()

  schema_gen(${bin}/book/schema.rst ${src}/book/schema_rst.py)
  schema_gen(${bin}/man/qdrouterd.conf.rst ${src}/man/qdrouterd_conf_man.py)

  add_custom_target(doc-schema DEPENDS ${SCHEMA_GEN})
  add_dependencies(doc doc-schema)

  # Generate rst text from --help output for man pages
  macro(help2rst program path)
    set(help ${bin}/man/${program}_help.rst)
    list(APPEND HELP_GEN ${help})
    add_custom_command (
      OUTPUT ${help}
      COMMAND ${RUN} -s ${src}/man/help2rst.py ${path}/${program} --help > ${help}
      DEPENDS ${path}/${program} ${schema_doc} ${src}/man/help2rst.py
      )
  endmacro()

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

  # Run sphinx to generate HTML and man pages
  if(USE_SPHINX)
    foreach(manpage qdmanage.8 qdrouterd.8 qdrouterd.conf.5 qdstat.8)
      list(APPEND MAN_PAGES ${bin}/man/${manpage})
      string(REGEX MATCH "[0-9]*$" section  ${manpage})
      install_doc(FILES ${bin}/man/${manpage}
        DESTINATION ${CMAKE_INSTALL_PREFIX}/${MAN_INSTALL_DIR}/man${section})
    endforeach()

    set(SPHINX_OUTPUT ${bin}/html/index.html ${bin}/singlehtml/book/book.html ${MAN_PAGES})

    set(html_raw_options -D html_theme=bare -D html_add_permalinks=".")
    add_custom_command(
      OUTPUT ${SPHINX_OUTPUT}
      # html/ contains plain HTML suitable for embedding in the Qpid website.
      COMMAND ${SPHINX_BUILD} -d ${bin}/doctrees -b html ${html_raw_options} ${bin} ${bin}/html
      # dochtml/ is a self-contained site with searching, navigation etc. installed with the docs.
      COMMAND ${SPHINX_BUILD} -d ${bin}/doctrees -b html ${bin} ${bin}/dochtml
      # man/ contains Unix man pages.
      COMMAND ${SPHINX_BUILD} -d ${bin}/doctrees -b man  ${bin} ${bin}/man
      DEPENDS ${RST_SRC} ${HELP_GEN} ${SCHEMA_GEN} 
      )
    add_custom_target(doc-sphinx DEPENDS ${SPHINX_OUTPUT})
    add_dependencies(doc doc-sphinx)

    install_doc(DIRECTORY ${bin}/dochtml/  DESTINATION ${QD_DOC_INSTALL_DIR}/html)
  endif(USE_SPHINX)

  # Install rst documentation as baseline in case we have no generator
  install(DIRECTORY ${bin}/ DESTINATION ${QD_DOC_INSTALL_DIR}/rst ${OPTIONAL} FILES_MATCHING PATTERN "*.rst")


endif(BUILD_DOCS)