mirror of
https://github.com/KhronosGroup/KTX-Software.git
synced 2026-01-18 17:41:19 +01:00
69b1685a7a
- Rework navigation among the multiple Doxygen projects for much easier use. - Rename new ktx tool man pages from `ktxtools_*` to `ktx_*` - Add `ktx` tool mainpage based on RELEASE_NOTES info. - Make minor formatting fix in `ktx` man page. - Update acknowledgements. - Remove outdated TODO.md. - Add script to do `$Date$` keyword smudging. Use it in CI and reference it from README.md to avoid repetition of list of files needing smudging. - Add `$Date$` keywords to some docs. - Remove `$Date$` and #ident keywords that are no longer needed or used. - Document the parts of `khr_df.h` relevant to the libktx API.
246 lines
8.5 KiB
CMake
246 lines
8.5 KiB
CMake
# Copyright 2015-2020 The Khronos Group Inc.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
find_package(Doxygen REQUIRED)
|
|
|
|
set(docdest "${CMAKE_CURRENT_BINARY_DIR}/docs")
|
|
|
|
# The torturous Doxygen output settings are a hack
|
|
# to workaround a doxygen limitation where it will
|
|
# only create the trailing directory of the path
|
|
# given in, e.g DOXYGEN_HTML_OUTPUT while enabling
|
|
# us to put each sub-document in its own directory of
|
|
# the html output.
|
|
|
|
# Global
|
|
set( DOXYGEN_PROJECT_LOGO icons/ktx_logo_200.png )
|
|
set( DOXYGEN_OUTPUT_DIRECTORY ${docdest}/html)
|
|
set( DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES )
|
|
set( DOXYGEN_EXTRACT_LOCAL_CLASSES NO )
|
|
set( DOXYGEN_HIDE_UNDOC_MEMBERS YES )
|
|
set( DOXYGEN_CASE_SENSE_NAMES YES )
|
|
set( DOXYGEN_SHOW_USED_FILES NO )
|
|
set( DOXYGEN_VERBATIM_HEADERS NO )
|
|
set( DOXYGEN_CLANG_ASSISTED_PARSING NO )
|
|
set( DOXYGEN_ALPHABETICAL_INDEX NO )
|
|
set( DOXYGEN_HTML_TIMESTAMP YES )
|
|
set( DOXYGEN_DISABLE_INDEX YES )
|
|
set( DOXYGEN_DISABLE_INDEX NO )
|
|
set( DOXYGEN_GENERATE_TREEVIEW YES )
|
|
set( DOXYGEN_GENERATE_LATEX NO )
|
|
set( DOXYGEN_GENERATE_HTML YES )
|
|
set( DOXYGEN_GENERATE_MAN YES )
|
|
set( DOXYGEN_MAN_OUTPUT ../man )
|
|
|
|
function( add_sources target sources )
|
|
# Make ${sources} show up in IDE/project
|
|
get_target_property( doc_sources ${target} SOURCES )
|
|
if( NOT doc_sources )
|
|
set( doc_sources "" ) # Clear doc_sources-NOTFOUND value.
|
|
endif()
|
|
set_target_properties(
|
|
${target}
|
|
PROPERTIES
|
|
SOURCES "${doc_sources};${sources}"
|
|
)
|
|
endfunction()
|
|
|
|
function( add_docs_cmake target )
|
|
# Make `docs.cmake` show up in IDE/project
|
|
add_sources( ${target} "cmake/docs.cmake" )
|
|
endfunction()
|
|
|
|
function( add_docs_cmake_plus target sources )
|
|
# Make `docs.cmake` plus ${sources} show up in IDE/project
|
|
add_sources( ${target} "cmake/docs.cmake;${sources}" )
|
|
endfunction()
|
|
|
|
# Note very well
|
|
#
|
|
# These projects and accompanying DOXYGEN_LAYOUT_FILES are carefully crafted
|
|
# to provide the illusion of a consistent GUI across all the projects.
|
|
# Likely this will be fragile in the face of Doxygen changes.
|
|
|
|
# ktx.doc
|
|
function( CreateDocLibKTX )
|
|
set( DOXYGEN_PROJECT_NAME "libktx Reference" )
|
|
set( DOXYGEN_ALIASES error=\"\\par Errors\\n\" )
|
|
set( DOXYGEN_LAYOUT_FILE pkgdoc/libktxDoxyLayout.xml )
|
|
set( DOXYGEN_TYPEDEF_HIDES_STRUCT YES )
|
|
set( DOXYGEN_EXCLUDE lib/uthash.h )
|
|
set( DOXYGEN_EXCLUDE_PATTERNS ktxint.h )
|
|
set( DOXYGEN_EXAMPLE_PATH examples lib )
|
|
# This does not hide the scope (class) names in the Modules list
|
|
# in the ToC. See https://github.com/doxygen/doxygen/issues/9921.
|
|
set( DOXYGEN_HIDE_SCOPE_NAMES YES )
|
|
set( DOXYGEN_HTML_OUTPUT libktx )
|
|
# Order is important here. '_' suffixed prefices must come first
|
|
# otherwise the non-suffixed is stripped first leaving just '_'.
|
|
set( DOXYGEN_IGNORE_PREFIX KTX_;ktx_;KTX;ktx )
|
|
set( DOXYGEN_MAN_LINKS YES )
|
|
set( DOXYGEN_MACRO_EXPANSION YES )
|
|
set( DOXYGEN_EXPAND_ONLY_PREDEF YES )
|
|
|
|
set( DOXYGEN_PREDEFINED
|
|
"KTXTEXTURECLASSDEFN=class_id classId\; \\
|
|
struct ktxTexture_vtbl* vtbl\; \\
|
|
struct ktxTexture_vvtbl* vvtbl\; \\
|
|
struct ktxTexture_protected* _protected\; \\
|
|
ktx_bool_t isArray\; \\
|
|
ktx_bool_t isCubemap\; \\
|
|
ktx_bool_t isCompressed\; \\
|
|
ktx_bool_t generateMipmaps\; \\
|
|
ktx_uint32_t baseWidth\; \\
|
|
ktx_uint32_t baseHeight\; \\
|
|
ktx_uint32_t baseDepth\; \\
|
|
ktx_uint32_t numDimensions\; \\
|
|
ktx_uint32_t numLevels\; \\
|
|
ktx_uint32_t numLayers\; \\
|
|
ktx_uint32_t numFaces\; \\
|
|
struct { \\
|
|
ktxOrientationX x\; \\
|
|
ktxOrientationY y\; \\
|
|
ktxOrientationZ z\; \\
|
|
} orientation\; \\
|
|
ktxHashList kvDataHead\; \\
|
|
ktx_uint32_t kvDataLen\; \\
|
|
ktx_uint8_t* kvData\; \\
|
|
ktx_size_t dataSize\; \\
|
|
ktx_uint8_t* pData\;"
|
|
)
|
|
#set( DOXYGEN_GENERATE_TAGFILE ${docdest}/libktx.tag )
|
|
|
|
doxygen_add_docs(
|
|
libktx.doc
|
|
lib/libktx_mainpage.md
|
|
include
|
|
lib/astc_encode.cpp
|
|
lib/basis_encode.cpp
|
|
lib/basis_transcode.cpp
|
|
lib/miniz_wrapper.cpp
|
|
lib/strings.c
|
|
lib/glloader.c
|
|
lib/hashlist.c
|
|
lib/filestream.c
|
|
lib/memstream.c
|
|
lib/texture.c
|
|
lib/texture1.c
|
|
lib/texture2.c
|
|
lib/vkloader.c
|
|
lib/writer1.c
|
|
lib/writer2.c
|
|
)
|
|
add_docs_cmake_plus( libktx.doc pkgdoc/libktxDoxyLayout.xml )
|
|
endfunction()
|
|
|
|
# ktxtools.doc
|
|
function( CreateDocTools )
|
|
set( DOXYGEN_PROJECT_NAME "KTX Tools Reference" )
|
|
set( DOXYGEN_FULL_PATH_NAMES NO )
|
|
set( DOXYGEN_ALIASES author=\"\\section AUTHOR\\n\" )
|
|
set( DOXYGEN_LAYOUT_FILE pkgdoc/toolsDoxyLayout.xml )
|
|
set( DOXYGEN_SHOW_FILES NO )
|
|
set( DOXYGEN_FILE_PATTERNS *.cpp )
|
|
set( DOXYGEN_RECURSIVE YES )
|
|
set( DOXYGEN_EXAMPLE_PATH utils tools )
|
|
set( DOXYGEN_HTML_OUTPUT ktxtools )
|
|
set( DOXYGEN_MAN_EXTENSION .1 )
|
|
#set( DOXYGEN_GENERATE_TAGFILE ${docdest}/ktxtools.tag )
|
|
set( DOXYGEN_TAGFILES ${docdest}/ktxpkg.tag=.. )
|
|
|
|
doxygen_add_docs(
|
|
tools.doc
|
|
tools/ktx/ktx_main.cpp
|
|
tools/ktx/command_create.cpp
|
|
tools/ktx/command_encode.cpp
|
|
tools/ktx/command_extract.cpp
|
|
tools/ktx/command_help.cpp
|
|
tools/ktx/command_info.cpp
|
|
tools/ktx/command_transcode.cpp
|
|
tools/ktx/command_validate.cpp
|
|
tools/ktx2check/ktx2check.cpp
|
|
tools/ktx2ktx2/ktx2ktx2.cpp
|
|
tools/ktxinfo/ktxinfo.cpp
|
|
tools/ktxsc/ktxsc.cpp
|
|
tools/ktxtools_mainpage.md
|
|
tools/toktx/toktx.cc
|
|
)
|
|
add_docs_cmake_plus( tools.doc pkgdoc/toolsDoxyLayout.xml )
|
|
endfunction()
|
|
|
|
# ktxjswrappers.doc
|
|
function( CreateDocJSWrappers )
|
|
set( DOXYGEN_PROJECT_NAME "KTX Javascript Wrappers Reference" )
|
|
set( DOXYGEN_FULL_PATH_NAMES NO )
|
|
set( DOXYGEN_ALIASES author=\"\\section AUTHOR\\n\" )
|
|
set( DOXYGEN_LAYOUT_FILE pkgdoc/jswrappersDoxyLayout.xml )
|
|
set( DOXYGEN_SHOW_FILES NO )
|
|
set( DOXYGEN_HTML_OUTPUT ktxjswrappers )
|
|
#set( DOXYGEN_GENERATE_TAGFILE ${docdest}/ktxjswrappers.tag )
|
|
set( DOXYGEN_TAGFILES ${docdest}/ktxpkg.tag=.. )
|
|
|
|
doxygen_add_docs(
|
|
jswrappers.doc
|
|
interface/js_binding
|
|
)
|
|
add_docs_cmake_plus( jswrappers.doc pkgdoc/jswrappersDoxyLayout.xml )
|
|
endfunction()
|
|
|
|
# ktxpkg.doc
|
|
function( CreateDocKTX )
|
|
set( DOXYGEN_PROJECT_NAME "Khronos Texture Software" )
|
|
set( DOXYGEN_ALIASES pversion=\"\\par Package Version\\n\" )
|
|
set( DOXYGEN_LAYOUT_FILE pkgdoc/packageDoxyLayout.xml )
|
|
set( DOXYGEN_EXCLUDE lib/uthash.h )
|
|
set( DOXYGEN_EXCLUDE_PATTERNS ktxint.h )
|
|
set( DOXYGEN_EXAMPLE_PATH lib )
|
|
set( DOXYGEN_GENERATE_TAGFILE ${docdest}/ktxpkg.tag )
|
|
set( DOXYGEN_HTML_HEADER pkgdoc/header.html )
|
|
set( DOXYGEN_HTML_OUTPUT . )
|
|
set( DOXYGEN_MAN_LINKS YES )
|
|
#set( DOXYGEN_TAGFILES ${docdest}/libktx.tag=libktx ${docdest}/ktxtools.tag=ktxtools )
|
|
|
|
doxygen_add_docs(
|
|
ktxpkg.doc
|
|
pkgdoc/pages.md
|
|
LICENSE.md
|
|
#RELEASE_NOTES.md
|
|
)
|
|
add_docs_cmake_plus( ktxpkg.doc pkgdoc/packageDoxyLayout.xml )
|
|
endfunction()
|
|
|
|
CreateDocLibKTX()
|
|
CreateDocTools()
|
|
CreateDocJSWrappers()
|
|
CreateDocKTX()
|
|
|
|
add_dependencies( libktx.doc ktxpkg.doc ktx_version )
|
|
add_dependencies( jswrappers.doc ktxpkg.doc )
|
|
add_dependencies( tools.doc ktxpkg.doc )
|
|
|
|
# I want to add a dependency on the "package" built-in target.
|
|
# Unfortunately CMake does not support adding dependencies to
|
|
# built-in targets. See https://gitlab.kitware.com/cmake/cmake/-/issues/8438.
|
|
#
|
|
# There also seems to be no way to add a dependency for the install commands
|
|
# below. Presumably "install(TARGETS ...)" adds a dependency on each target
|
|
# but the rest of that command is simply not appropriate for this case.
|
|
add_custom_target( all.doc ALL
|
|
DEPENDS tools.doc libktx.doc jswrappers.doc
|
|
)
|
|
|
|
install(
|
|
DIRECTORY ${docdest}/html
|
|
DESTINATION "${CMAKE_INSTALL_DOCDIR}"
|
|
COMPONENT tools
|
|
)
|
|
|
|
install(
|
|
DIRECTORY ${docdest}/man/man1
|
|
## Omit those, since at the moment they contain a lot of undesired files generated by Doxygen
|
|
# ${docdest}/man/man3
|
|
# ${docdest}/man/ktx/man3
|
|
DESTINATION "${CMAKE_INSTALL_MANDIR}"
|
|
COMPONENT tools
|
|
)
|