doc_makeall.cmake.in

# -------------------------------------------------------------------------
# Doxygen documentation batch
# -------------------------------------------------------------------------

set(DOXYGEN "@DOXYGEN@")
set(DOXYGEN_DOT_EXECUTABLE "@DOXYGEN_DOT_EXECUTABLE@")
set(HTML_HELP_COMPILER "@HTML_HELP_COMPILER@")
set(PERL "@PERL@")
set(DOXYGEN_KEEP_TEMP "@DOXYGEN_KEEP_TEMP@")

if(NOT DOXYGEN)
  message(FATAL_ERROR "error: cannot build ParaView documentation without doxygen")
endif()
if(NOT DOXYGEN_DOT_EXECUTABLE)
  message(FATAL_ERROR "error: cannot build ParaView documentation without dot")
endif()
if(NOT PERL)
  message(FATAL_ERROR "error: cannot build ParaView documentation without perl")
endif()

# PROJECT_NAME:
# Documentation/project name. Used in some of the resulting file names and
# xrefs to uniquify two or more projects linked together through their
# Doxygen's tag files. Mandatory for each documentation set.
# Note: might be the same as the doxyfile's PROJECT_NAME
# Example:
#   PROJECT_NAME=ParaView
#
set (PROJECT_NAME ParaView)

# PATH_TO_VTK_DOX_SCRIPTS:
# Path to the directory holding the Perl scripts used to produce the VTK doc
# in Doxygen format. You need the VTK source files or a local copy of
# these scripts.
# Example:
#   PATH_TO_VTK_DOX_SCRIPTS=@ParaView_SOURCE_DIR@/Utilities/Doxygen
#
set(PATH_TO_VTK_DOX_SCRIPTS "@ParaView_SOURCE_DIR@/VTK/Utilities/Doxygen")
set(PATH_TO_PARAVIEW_DOX_SCRIPTS "@ParaView_SOURCE_DIR@/Utilities/Doxygen")

# SOURCE_DIR:
# Source directory. The top directory of the source files.
# Example:
#   SOURCE_DIR=@ParaView_SOURCE_DIR@
#
set(SOURCE_DIR "@ParaView_SOURCE_DIR@")

# REL_PATH_TO_TOP:
# Relative path from the top directory of the source files to the directory
# (or top directory) holding the files to document. Useful if several parts
# of the same source directory should be documented separately.
# Example:
#   REL_PATH_TO_TOP=.
#   REL_PATH_TO_TOP=framework/src
set(REL_PATH_TO_TOP .)

# INTERMEDIATE_DOX_DIR:
# Directory where the intermediate Doxygen files should be stored (mainly
# these headers files converted from the VTK format to the Doxygen format).
# This directory is erased at the end of this script, unless you comment
# the corresponding line.
# DOXTEMP might be used to simplify the syntax.
# Example:
#   DOXTEMP=DOXTEMP=@ParaView_BINARY_DIR@/Utilities/Doxygen
#   INTERMEDIATE_DOX_DIR=$DOXTEMP/dox
#
set(DOXTEMP "@CMAKE_CURRENT_BINARY_DIR@")
set(INTERMEDIATE_DOX_DIR "${DOXTEMP}/dox")

# DATA_ROOT:
# Data directory. The root directory of the data files.
# Example:
#   DATA_ROOT=@VTK_DATA_ROOT@
#
set(DATA_ROOT "@PARAVIEW_DATA_ROOT@")

# GITWEB, GITWEB_SUFFIX, GITWEB_CHECKOUT,
# GITWEB_DATA, GITWEB_DATA_SUFFIX, GITWEB_DATA_CHECKOUT:
# URL to the GITWeb of the project + same in checkout mode (i.e. appending a
# file  name to this URL will retrieve the contents of the file). In the same way
# GITWEB_SUFFIX will be appended to the result.
# Same applies to GITWEB_DATA, which is the URL to the GITWeb
# of the Data's project.
# Example:
#   GITWEB=http://public.kitware.com/cgi-bin/viewcvs.cgi
#   GITWEB_SUFFIX=?root=VTK
#   GITWEB_CHECKOUT=http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*
#   GITWEB_DATA=http://public.kitware.com/cgi-bin/viewcvs.cgi
#   GITWEB_DATA_SUFFIX=?root=VTKData
#   GITWEB_DATA_CHECKOUT=http://public.kitware.com/cgi-bin/viewcvs.cgi/*checkout*
#
set(GITWEB http://paraview.org/gitweb) # not used
set(GITWEB_SUFFIX ) #empty for git ?p=VTK)
set(GITWEB_CHECKOUT http://paraview.org/gitweb?p=ParaView.git;a=blob;f=)
set(GITWEB_DATA http://paraview.org/gitweb)
set(GITWEB_DATA_SUFFIX ) # empty for git ?p=VTKData)
set(GITWEB_DATA_CHECKOUT http://paraview.org/gitweb?p=ParaViewData.git;a=blob;f=)

# DOXYFILE:
# Path to the Doxygen configuration file (i.e. doxyfile).
# Example:
#   DOXYFILE $DOXTEMP/doxyfile
#
set(DOXYFILE "${DOXTEMP}/doxyfile")

# OUTPUT_DIRECTORY ALLOW_ERASE_OUTPUT_DIRECTORY:
# Path to the Doxygen output directory (where the resulting doc is stored).
# Note: should be the same as your doxyfile's OUTPUT_DIRECTORY
# If ON, allows the output directory to be erased when some advanced output
# file have been produced (HTML Help, or TAR archive for example).
# Example:
#   OUTPUT_DIRECTORY $DOXTEMP/doc
#   ALLOW_ERASE_OUTPUT_DIRECTORY ON
#
set(OUTPUT_DIRECTORY "${DOXTEMP}/doc")
set(ALLOW_ERASE_OUTPUT_DIRECTORY ON)

# COMPILE_HTML_HELP RESULTING_HTML_HELP_FILE:
# Compile the CHM (Compressed HTML) HTML Help file, name of the resulting
# file. If set to ON and name is non-empty these options will actually
# trigger the HTML-Help compiler to create the CHM. The resulting
# file (usually index.chm) will be renamed to this name.
# Note: if ON, the whole $OUTPUT_DIRECTORY will be erased at the end of
#       this script, since this file is considered to be one of the
#       advanced final output, unless ALLOW_ERASE_OUTPUT_DIRECTORY is OFF
# Note: your doxyfile should be configured to enable HTML Help creation
#       (using GENERATE_HTML   YES, GENERATE_HTMLHELP   YES)
# Example:
#   COMPILE_HTML_HELP ON
#   COMPILE_HTML_HELP @DOCUMENTATION_HTML_HELP@
#   RESULTING_HTML_HELP_FILE $DOXTEMP/vtk@PARAVIEW_VERSION_MAJOR@.@PARAVIEW_VERSION_MINOR@.chm
#
set(COMPILE_HTML_HELP OFF)
set(RESULTING_HTML_HELP_FILE "${DOXTEMP}/vtk@PARAVIEW_VERSION_MAJOR@.@PARAVIEW_VERSION_MINOR@.chm")

# CREATE_HTML_TARZ_ARCHIVE RESULTING_HTML_TARZ_ARCHIVE_FILE:
# Create a compressed (gzip) tar archive of the html directory (located
# under the OUTPUT_DIRECTORY), and name of the resulting archive file.
# Note: your doxyfile should be configured to enable HTML creation
#       (using GENERATE_HTML   YES)
# Example:
#   CREATE_HTML_TARZ_ARCHIVE ON
#   CREATE_HTML_TARZ_ARCHIVE @DOCUMENTATION_HTML_TARZ@
#   RESULTING_HTML_TARZ_ARCHIVE_FILE $DOXTEMP/vtk@PARAVIEW_VERSION_MAJOR@.@PARAVIEW_VERSION_MINOR@-html.tar.gz
#
set(CREATE_HTML_TARZ_ARCHIVE OFF)
set(RESULTING_HTML_TARZ_ARCHIVE_FILE "${DOXTEMP}/ParaView-html.tar.gz")

# DOWNLOAD_VTK_TAGFILE VTK_TAGFILE VTK_TAGFILE_REMOTE_DIR VTK_TAGFILE_DEST_DIR:
# Download the VTK tag file, name, remote location and destination dir of this
# tag file. If set to ON, the tag file is retrieved from its remote location
# using wget and stored in the destination dir. It will be automatically
# deleted at the end of this script.
# Note: your doxyfile must be tailored to make use-of or create this tag file.
#    (using TAGFILES = vtk@PARAVIEW_VERSION_MAJOR@-nightly.tag=http://www.vtk.org/doc/nightly/html
#        or GENERATE_TAGFILE = "@ParaView_BINARY_DIR@/Utilities/Doxygen/vtk@PARAVIEW_VERSION_MAJOR@.@PARAVIEW_VERSION_MINOR@.tag")
# Example:
#   DOWNLOAD_VTK_TAGFILE=OFF
#   VTK_TAGFILE=vtk@PARAVIEW_VERSION_MAJOR@-nightly.tag
#   VTK_TAGFILE_REMOTE_DIR=http://www.vtk.org/doc/nightly/html
#   VTK_TAGFILE_DEST_DIR=$DOXTEMP
#
set(DOWNLOAD_VTK_TAGFILE ON)
set(VTK_TAGFILE vtkNightlyDoc.tag.gz)
set(VTK_TAGFILE_REMOTE_DIR http://www.vtk.org/files/nightly)
set(VTK_TAGFILE_DEST_DIR "${DOXTEMP}")

# ----------------------------------------------------------------------------
# SOURCE_DIRECTORIES
#
# This list is processed by several perl scripts below. Keeping it in one
# list avoids the possibility that multiple lists might get out of sync with
# rushed edits...
#
set(SOURCE_DIRECTORIES
@PV_MODULE_DIRS_DOXYGEN@
)

# ----------------------------------------------------------------------------
# Print some progress. Be nice to the build watcher.

macro(step n desc)
  message(STATUS "")
  message(STATUS "Building VTK docs: step ${n} of 13, (${desc})")
  message(STATUS "----------------------------------------------------------------------------")
endmacro()

macro(echo v)
  message(STATUS "${v}='${${v}}'")
endmacro()

# ----------------------------------------------------------------------------
# Values of this script's variables:

message(STATUS "")
message(STATUS "Building VTK Documentation: initial variable values")
message(STATUS "----------------------------------------------------------------------------")

foreach(var
  CMAKE_CURRENT_LIST_FILE
  CMAKE_MAJOR_VERSION
  CMAKE_MINOR_VERSION
  CMAKE_PATCH_VERSION
  DOXYGEN
  DOXYGEN_DOT_EXECUTABLE
  HTML_HELP_COMPILER
  PERL
  PROJECT_NAME
  PATH_TO_VTK_DOX_SCRIPTS
  SOURCE_DIR
  REL_PATH_TO_TOP
  DOXTEMP
  INTERMEDIATE_DOX_DIR
  DATA_ROOT
  GITWEB
  GITWEB_SUFFIX
  GITWEB_CHECKOUT
  GITWEB_DATA
  GITWEB_DATA_SUFFIX
  GITWEB_DATA_CHECKOUT
  DOXYFILE
  OUTPUT_DIRECTORY
  ALLOW_ERASE_OUTPUT_DIRECTORY
  COMPILE_HTML_HELP
  RESULTING_HTML_HELP_FILE
  CREATE_HTML_TARZ_ARCHIVE
  RESULTING_HTML_TARZ_ARCHIVE_FILE
  DOWNLOAD_VTK_TAGFILE
  VTK_TAGFILE
  VTK_TAGFILE_REMOTE_DIR
  VTK_TAGFILE_DEST_DIR
  SOURCE_DIRECTORIES
)
  echo(${var})
endforeach()

# ----------------------------------------------------------------------------
# Convert the VTK headers to the Doxygen format.

step(1 "convert VTK headers to doxygen format")
file(MAKE_DIRECTORY "${INTERMEDIATE_DOX_DIR}")
#execute_process(COMMAND ${PERL}
#  "${PATH_TO_VTK_DOX_SCRIPTS}/doc_header2doxygen.pl"
#  --to "${INTERMEDIATE_DOX_DIR}"
#  --relativeto "${SOURCE_DIR}/${REL_PATH_TO_TOP}"
#  ${SOURCE_DIRECTORIES}
#  RESULT_VARIABLE rv
#)
#
#if (rv)
#  message(FATAL_ERROR "Step failed: ${rv}")
#endif()

# ----------------------------------------------------------------------------
# Build the Events invocation list.

step(2 "cross-reference classes to InvokeEvent callers")
execute_process(COMMAND ${PERL}
  "${PATH_TO_VTK_DOX_SCRIPTS}/doc_codematch.pl"
  --codematch "\\w(?:->|\\.)InvokeEvent\\s*\\(\\s*(vtkCommand::\\w+)[\\s,]"
  --label "Events"
  --project "${PROJECT_NAME}"
  --sectionmatch "^vtkCommand::(\\w)"
  --store "doc_${PROJECT_NAME}_events.dox"
  --title "Event to Classes"
  --sectionmatch2 "^vtk(\\w)"
  --store2 "doc_${PROJECT_NAME}_events2.dox"
  --title2 "Class to Events"
  --to "${INTERMEDIATE_DOX_DIR}"
  --unique "v"
  --relativeto "${SOURCE_DIR}/${REL_PATH_TO_TOP}"
  ${SOURCE_DIRECTORIES}
  RESULT_VARIABLE rv
)

if (rv)
  message(FATAL_ERROR "Step failed: ${rv}")
endif()

# ----------------------------------------------------------------------------
# Build the full-text index.

step(3 "build full text index -- skipping")
# execute_process(COMMAND ${PERL}
#   "${PATH_TO_VTK_DOX_SCRIPTS}/doc_index.pl"
#   --project "${PROJECT_NAME}"
#   --stop  "${PATH_TO_VTK_DOX_SCRIPTS}/doc_index.stop"
#   --store "doc_${PROJECT_NAME}_index.dox"
#   --to "${INTERMEDIATE_DOX_DIR}"
#   ${SOURCE_DIRECTORIES}
#   RESULT_VARIABLE rv
# )
#
# if (rv)
#   message(FATAL_ERROR "Step failed: ${rv}")
# endif()

# ----------------------------------------------------------------------------
# Extract the VTK version and create the main page.
#  -- Here we differ from VTK, we simply install the generated
#  doc_ParaView_version.dox file instead.
step(4 "extract ParaView version")
#file(INSTALL "${DOXTEMP}/doc_ParaView_version.dox"
#     DESTINATION "${INTERMEDIATE_DOX_DIR}"
#     USE_SOURCE_PERMISSIONS)

# ----------------------------------------------------------------------------
# Generate the 'Class to Examples' page cross-linking each class to these
# examples that use that class.

step(5 "cross-reference classes with Examples -- skipping")
#execute_process(COMMAND ${PERL}
#  "${PATH_TO_VTK_DOX_SCRIPTS}/doc_class2example.pl"
#  --baselinedir "${DATA_ROOT}/Baseline"
#  --baselineicon "pic.gif"
#  --baselinelink "${GITWEB_DATA_CHECKOUT}Baseline"
#  --baselinelinksuffix "${GITWEB_DATA_SUFFIX}"
#  --datamatch "\\W(VTK_DATA_ROOT|VTKData|(vtk)?GetDataRoot|ExpandDataFileName)\\W"
#  --dataicon "paper-clip.gif"
#  --dirmatch "^Examples$"
#  --label "Examples"
#  --link "${GITWEB_CHECKOUT}"
#  --linksuffix "${GITWEB_SUFFIX}"
#  --project "${PROJECT_NAME}"
#  --store "doc_${PROJECT_NAME}_class2examples.dox"
#  --title "Class To Examples"
#  --to "${INTERMEDIATE_DOX_DIR}"
#  --unique "e"
#  --remove_leading_slash=1
#  "${SOURCE_DIR}/${REL_PATH_TO_TOP}"
#  RESULT_VARIABLE rv
#)

# ----------------------------------------------------------------------------
# Generate the 'Class to Tests' page cross-linking each class to these
# tests that use that class.

step(6 "cross-reference classes with Testing -- skipping")
#execute_process(COMMAND ${PERL}
#  "${PATH_TO_VTK_DOX_SCRIPTS}/doc_class2example.pl"
#  --baselinedir "${DATA_ROOT}/Baseline"
#  --baselineicon "pic.gif"
#  --baselinelink "${GITWEB_DATA_CHECKOUT}Baseline"
#  --baselinelinksuffix "${GITWEB_DATA_SUFFIX}"
#  --datamatch "\\W(VTK_DATA_ROOT|VTKData|(vtk)?GetDataRoot|ExpandDataFileName)\\W"
#  --dataicon "paper-clip.gif"
#  --dirmatch "^Testing$"
#  --label "Tests"
#  --link "${GITWEB_CHECKOUT}"
#  --linksuffix "${GITWEB_SUFFIX}"
#  --project "${PROJECT_NAME}"
#  --store "doc_${PROJECT_NAME}_class2tests.dox"
#  --title "Class To Tests"
#  --to "${INTERMEDIATE_DOX_DIR}"
#  --unique "t"
#  --remove_leading_slash=1
#  "${SOURCE_DIR}/${REL_PATH_TO_TOP}"
#  RESULT_VARIABLE rv
#)

# ----------------------------------------------------------------------------
# Retrieve the remote VTK tag file.

step(7 "download VTK tag file")
if(DOWNLOAD_VTK_TAGFILE AND EXISTS "@GUNZIPCOMMAND@")
  if(NOT VTK_TAGFILE STREQUAL "")
    file(DOWNLOAD
      "${VTK_TAGFILE_REMOTE_DIR}/${VTK_TAGFILE}"
      "${VTK_TAGFILE_DEST_DIR}/${VTK_TAGFILE}"
      TIMEOUT 60
    )
    if(NOT EXISTS "${VTK_TAGFILE_DEST_DIR}/${VTK_TAGFILE}")
      message(STATUS "warning: VTK tag file did not download correctly")
    else()
      message(STATUS "Download ${VTK_TAGFILE_DEST_DIR}/${VTK_TAGFILE}")
      execute_process(COMMAND
        "@GUNZIPCOMMAND@" "${VTK_TAGFILE_DEST_DIR}/${VTK_TAGFILE}")
    endif()
  endif()
endif()

# ----------------------------------------------------------------------------
# Create the Doxygen doc.

step(8 "run doxygen")
file(REMOVE_RECURSE "${OUTPUT_DIRECTORY}")
file(MAKE_DIRECTORY "${OUTPUT_DIRECTORY}")
execute_process(COMMAND ${DOXYGEN} ${DOXYFILE}
  RESULT_VARIABLE rv
)
if (rv)
  message(FATAL_ERROR "Doxygen command failed: ${rv}")
endif()

# ----------------------------------------------------------------------------
# Clean the HTML pages to remove the path to the intermediate Doxygen dir.

step(9 "remove intermediate path from html")
execute_process(COMMAND ${PERL}
  "${PATH_TO_VTK_DOX_SCRIPTS}/doc_rmpath.pl"
  --to "${INTERMEDIATE_DOX_DIR}"
  --html "${OUTPUT_DIRECTORY}/html"
  RESULT_VARIABLE rv
)

if (rv)
  message(FATAL_ERROR "Step failed: ${rv}")
endif()

# ----------------------------------------------------------------------------
# clean the HTML pages to remove layout problems

step(10 "clean html to remove layout problems - skipping")
#execute_process(COMMAND ${PERL}
#  "${PATH_TO_VTK_DOX_SCRIPTS}/doc_cleanhtml.pl"
#  --html "${OUTPUT_DIRECTORY}/html"
#  RESULT_VARIABLE rv
#)
#
#if (rv)
#  message(FATAL_ERROR "Step failed: ${rv}")
#endif()

# ----------------------------------------------------------------------------
# Create the *.chm file

step(11 "build *.chm file")
if(COMPILE_HTML_HELP AND HTML_HELP_COMPILER)
  if(NOT "${RESULTING_HTML_HELP_FILE}" STREQUAL "")
    if(EXISTS "${OUTPUT_DIRECTORY}/html/index.hhp")
      # hhc creates index.chm next to index.hhp
      execute_process(COMMAND ${HTML_HELP_COMPILER} index.hhp
        WORKING_DIRECTORY "${OUTPUT_DIRECTORY}/html"
        RESULT_VARIABLE rv
      )

      if (rv)
        message(FATAL_ERROR "Command failed: ${rv}")
      endif()
    else()
      message(STATUS "warning: no index.hhp file, not running HTML Help Compiler...")
    endif()

    if(EXISTS "${OUTPUT_DIRECTORY}/html/index.chm")
      # copy it to where we want it
      execute_process(COMMAND ${CMAKE_COMMAND} -E copy
        "${OUTPUT_DIRECTORY}/html/index.chm"
        "${RESULTING_HTML_HELP_FILE}"
        RESULT_VARIABLE rv
      )

      # get rid of the one in the html dir
      file(REMOVE "${OUTPUT_DIRECTORY}/html/index.chm")
    else()
      message(STATUS "warning: no index.chm file, not moving to final location...")
    endif()
  endif()
endif()

# ----------------------------------------------------------------------------
# Create the *.tar.gz file

if(CREATE_HTML_TARZ_ARCHIVE)
  step(12 "build *.tar.gz file")
  if(NOT RESULTING_HTML_TARZ_ARCHIVE_FILE STREQUAL "")
    execute_process(COMMAND ${CMAKE_COMMAND} -E tar cfz ${RESULTING_HTML_TARZ_ARCHIVE_FILE} html
      WORKING_DIRECTORY ${OUTPUT_DIRECTORY}
      RESULT_VARIABLE rv
    )

    if (rv)
      message(FATAL_ERROR "Command failed: ${rv}")
    endif()
  endif()
else()
  step(12 "build *.tar.gz file -- skipping")
endif()

# ----------------------------------------------------------------------------
# Clean-up.

if(DOXYGEN_KEEP_TEMP)
  message("Skipping step 13: clean up.")
else()
  step(13 "clean up")
  file(REMOVE_RECURSE "${INTERMEDIATE_DOX_DIR}")

  if(DOWNLOAD_VTK_TAGFILE)
    if(NOT VTK_TAGFILE STREQUAL "")
      file(REMOVE "${VTK_TAGFILE_DEST_DIR}/${VTK_TAGFILE}")
   endif()
  endif()

  if(COMPILE_HTML_HELP)
    if(NOT RESULTING_HTML_HELP_FILE STREQUAL "")
      if(ALLOW_ERASE_OUTPUT_DIRECTORY)
        file(REMOVE_RECURSE "${OUTPUT_DIRECTORY}")
      endif()
    endif()
  endif()
endif()

#
# If you add more steps, please update the step macro to reflect the total
# number of steps in the progressive build output... Thanks.
#