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