docs.cmake

   1 ##
   2 ## Copyright (c) 2017, Alliance for Open Media. All rights reserved
   3 ##
   4 ## This source code is subject to the terms of the BSD 2 Clause License and
   5 ## the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
   6 ## was not distributed with this source code in the LICENSE file, you can
   7 ## obtain it at www.aomedia.org/license/software. If the Alliance for Open
   8 ## Media Patent License 1.0 was not distributed with this source code in the
   9 ## PATENTS file, you can obtain it at www.aomedia.org/license/patent.
  10 ##
  11 if (NOT AOM_DOCS_CMAKE_)
  12 set(AOM_DOCS_CMAKE_ 1)
  13
  14 cmake_minimum_required(VERSION 3.5)
  15
  16 set(AOM_DOXYFILE "${AOM_CONFIG_DIR}/doxyfile")
  17 set(AOM_DOXYGEN_CONFIG_TEMPLATE "libs.doxy_template")
  18 set(AOM_DOXYGEN_OUTPUT_DIR "${AOM_CONFIG_DIR}/dox")
  19 set(AOM_DOXYGEN_SECTIONS "av1")
  20
  21 set(AOM_DOXYGEN_SOURCES
  22     "${AOM_ROOT}/aom/aom.h"
  23     "${AOM_ROOT}/aom/aom_codec.h"
  24     "${AOM_ROOT}/aom/aom_frame_buffer.h"
  25     "${AOM_ROOT}/aom/aom_image.h"
  26     "${AOM_ROOT}/aom/aom_integer.h"
  27     "${AOM_ROOT}/keywords.dox"
  28     "${AOM_ROOT}/mainpage.dox"
  29     "${AOM_ROOT}/usage.dox")
  30
  31 if (CONFIG_AV1_DECODER)
  32   set(AOM_DOXYGEN_EXAMPLE_SOURCES
  33       ${AOM_DOXYGEN_EXAMPLE_SOURCES}
  34       "${AOM_ROOT}/aomdec.c"
  35       "${AOM_ROOT}/examples/decode_to_md5.c"
  36       "${AOM_ROOT}/examples/decode_with_drops.c"
  37       "${AOM_ROOT}/examples/simple_decoder.c")
  38
  39   set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS
  40       ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS}
  41       "Full featured decoder."
  42       "Frame by frame MD5 checksum."
  43       "Drops frames while decoding."
  44       "Simplified decoder loop.")
  45
  46   set(AOM_DOXYGEN_SECTIONS ${AOM_DOXYGEN_SECTIONS} "av1_decoder decoder")
  47
  48   set(AOM_DOXYGEN_SOURCES
  49       ${AOM_DOXYGEN_SOURCES}
  50       "${AOM_ROOT}/aom/aom_decoder.h"
  51       "${AOM_ROOT}/aom/aomdx.h"
  52       "${AOM_ROOT}/usage_dx.dox")
  53
  54   if (CONFIG_ANALYZER)
  55     set(AOM_DOXYGEN_EXAMPLE_SOURCES
  56         ${AOM_DOXYGEN_EXAMPLE_SOURCES}
  57         "${AOM_ROOT}/examples/analyzer.cc")
  58
  59     set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS
  60         ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS}
  61         "Bitstream analyzer.")
  62   endif ()
  63
  64   if (CONFIG_INSPECTION)
  65      set(AOM_DOXYGEN_EXAMPLE_SOURCES
  66          ${AOM_DOXYGEN_EXAMPLE_SOURCES}
  67          "${AOM_ROOT}/examples/inspect.c")
  68
  69     set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS
  70         ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS}
  71         "Bitstream inspector.")
  72   endif ()
  73 endif ()
  74
  75 if (CONFIG_AV1_ENCODER)
  76   set(AOM_DOXYGEN_EXAMPLE_SOURCES
  77       ${AOM_DOXYGEN_EXAMPLE_SOURCES}
  78       "${AOM_ROOT}/aomenc.c"
  79       "${AOM_ROOT}/examples/lossless_encoder.c"
  80       "${AOM_ROOT}/examples/set_maps.c"
  81       "${AOM_ROOT}/examples/simple_encoder.c"
  82       "${AOM_ROOT}/examples/twopass_encoder.c")
  83
  84   set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS
  85       ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS}
  86       "Full featured encoder."
  87       "Simplified lossless encoder."
  88       "Set active and ROI maps."
  89       "Simplified encoder loop."
  90       "Two-pass encoder loop.")
  91
  92   if (CONFIG_SCALABILITY)
  93     set(AOM_DOXYGEN_EXAMPLE_SOURCES
  94         ${AOM_DOXYGEN_EXAMPLE_SOURCES}
  95         "${AOM_ROOT}/examples/scalable_encoder.c")
  96
  97     set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS
  98         ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS}
  99         "Scalable encoder loop.")
 100   endif ()
 101
 102   set(AOM_DOXYGEN_SECTIONS ${AOM_DOXYGEN_SECTIONS} "av1_encoder encoder")
 103
 104   set(AOM_DOXYGEN_SOURCES
 105       ${AOM_DOXYGEN_SOURCES}
 106       "${AOM_ROOT}/aom/aomcx.h"
 107       "${AOM_ROOT}/aom/aom_encoder.h"
 108       "${AOM_ROOT}/usage_cx.dox")
 109 endif ()
 110
 111 if (CONFIG_AV1_DECODER AND CONFIG_AV1_ENCODER)
 112   set(AOM_DOXYGEN_EXAMPLE_SOURCES
 113       ${AOM_DOXYGEN_EXAMPLE_SOURCES}
 114       "${AOM_ROOT}/examples/aom_cx_set_ref.c")
 115
 116   set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS
 117       ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS}
 118       "Set encoder reference frame.")
 119 endif ()
 120
 121 # Iterates over list named by $list_name and appends each item to $AOM_DOXYFILE
 122 # as values assigned to $var_name with no line breaks between list items.
 123 # Appends a new line after the entire config variable is expanded.
 124 function (write_cmake_list_to_doxygen_config_var var_name list_name)
 125   unset(output_string)
 126   foreach (list_item ${${list_name}})
 127     set(output_string "${output_string} ${list_item} ")
 128   endforeach ()
 129   string(STRIP "${output_string}" output_string)
 130   file(APPEND "${AOM_DOXYFILE}" "${var_name} += ${output_string}\n")
 131 endfunction ()
 132
 133 function (get_name file_path name_var)
 134     get_filename_component(file_basename ${file_path} NAME)
 135     get_filename_component(${name_var} ${file_basename} NAME_WE)
 136     set(${name_var} ${${name_var}} PARENT_SCOPE)
 137 endfunction ()
 138
 139 function (setup_documentation_targets)
 140   # Sanity check: the lengths of these lists must match.
 141   list(LENGTH AOM_DOXYGEN_EXAMPLE_SOURCES num_sources)
 142   list(LENGTH AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS num_descs)
 143   if (NOT ${num_sources} EQUAL ${num_descs})
 144     message(FATAL_ERROR "Unqeual example and description totals.")
 145   endif ()
 146
 147   # Take the list of examples and produce example_basename.dox for each file in
 148   # the list.
 149   file(MAKE_DIRECTORY "${AOM_DOXYGEN_OUTPUT_DIR}")
 150   foreach (example_file ${AOM_DOXYGEN_EXAMPLE_SOURCES})
 151     unset(example_basename)
 152     get_name("${example_file}" "example_name")
 153     set(example_dox "${AOM_DOXYGEN_OUTPUT_DIR}/${example_name}.dox")
 154     set(dox_string "/*!\\page example_${example_name} ${example_name}\n")
 155     set(dox_string "${dox_string} \\includelineno ${example_file}\n*/\n")
 156     file(WRITE "${example_dox}" ${dox_string})
 157     set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES} "${example_dox}")
 158   endforeach ()
 159
 160   # Generate samples.dox, an index page that refers to the example_basename.dox
 161   # files that were just created.
 162   set(samples_header
 163 "
 164 /*!\\page samples Sample Code
 165 This SDK includes a number of sample applications. Each sample documents a
 166 feature of the SDK in both prose and the associated C code. The following
 167 samples are included:
 168 ")
 169
 170   set(utils_desc
 171 "
 172 In addition, the SDK contains a number of utilities. Since these utilities are
 173 built upon the concepts described in the sample code listed above, they are not
 174 documented in pieces like the samples are. Their source is included here for
 175 reference. The following utilities are included:
 176 ")
 177
 178   # Write the description for the samples section.
 179   set(samples_dox "${AOM_CONFIG_DIR}/samples.dox")
 180   file(WRITE "${samples_dox}" "${samples_header}\n")
 181
 182   # Iterate over $AOM_DOXYGEN_EXAMPLE_SOURCES and
 183   # $AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS and massage example names as required by
 184   # AV1's doxygen setup.
 185   math(EXPR max_example_index "${num_sources} - 1")
 186   foreach (NUM RANGE ${max_example_index})
 187     list(GET AOM_DOXYGEN_EXAMPLE_SOURCES ${NUM} ex_name)
 188     get_name("${ex_name}" "ex_name")
 189
 190     # AV1's doxygen lists aomdec and aomenc as utils apart from the examples.
 191     # Save the indexes for another pass.
 192     if ("${ex_name}" MATCHES "aomdec\|aomenc")
 193       set(util_indexes "${util_indexes}" "${NUM}")
 194       continue()
 195     endif ()
 196     list(GET AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${NUM} ex_desc)
 197     file(APPEND "${samples_dox}" " - \\subpage example_${ex_name} ${ex_desc}\n")
 198   endforeach ()
 199
 200   # Write the description and index for the utils.
 201   file(APPEND "${samples_dox}" "${utils_desc}\n")
 202   foreach (util_index ${util_indexes})
 203     list(GET AOM_DOXYGEN_EXAMPLE_SOURCES ${util_index} ex_name)
 204     get_name("${ex_name}" "ex_name")
 205     list(GET AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${util_index} ex_desc)
 206     file(APPEND "${samples_dox}" " - \\subpage example_${ex_name} ${ex_desc}\n")
 207   endforeach ()
 208   file(APPEND "${samples_dox}" "*/")
 209
 210   # Add $samples_dox to the doxygen inputs.
 211   get_filename_component(samples_dox ${samples_dox} NAME)
 212   set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES} ${samples_dox})
 213
 214   # Generate libaom's doxyfile.
 215   file(WRITE "${AOM_DOXYFILE}" "##\n## GENERATED FILE. DO NOT EDIT\n##\n")
 216   file(READ "${AOM_ROOT}/${AOM_DOXYGEN_CONFIG_TEMPLATE}" doxygen_template_data)
 217   file(APPEND "${AOM_DOXYFILE}" ${doxygen_template_data})
 218   file(APPEND "${AOM_DOXYFILE}"
 219        "EXAMPLE_PATH += ${AOM_ROOT} ${AOM_ROOT}/examples\n")
 220   file(APPEND
 221        "${AOM_DOXYFILE}" "INCLUDE_PATH += ${AOM_CONFIG_DIR} ${AOM_ROOT}\n")
 222   file(APPEND "${AOM_DOXYFILE}"
 223        "STRIP_FROM_PATH += ${AOM_ROOT} ${AOM_CONFIG_DIR}\n")
 224   write_cmake_list_to_doxygen_config_var("INPUT" "AOM_DOXYGEN_SOURCES")
 225   write_cmake_list_to_doxygen_config_var("ENABLED_SECTIONS"
 226                                          "AOM_DOXYGEN_SECTIONS")
 227
 228   # Add the doxygen generation rule.
 229   add_custom_target(docs ALL
 230                     COMMAND "${DOXYGEN_EXECUTABLE}" "${AOM_DOXYFILE}"
 231                     DEPENDS "${AOM_DOXYFILE}" ${AOM_DOXYGEN_SOURCES}
 232                              ${AOM_DOXYGEN_EXAMPLE_SOURCES}
 233                              "${AOM_DOXYGEN_CONFIG_TEMPLATE}"
 234                     SOURCES "${AOM_DOXYFILE}" ${AOM_DOXYGEN_SOURCES}
 235                              ${AOM_DOXYGEN_EXAMPLE_SOURCES}
 236                              "${AOM_DOXYGEN_CONFIG_TEMPLATE}")
 237 endfunction ()
 238
 239 endif ()  # AOM_DOCS_CMAKE_