Improve documentation (KhronosGroup#730)

- 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.
KaperD · Jul 5, 2023 · db4fca7 · db4fca7
1 parent dbd9ff0
commit db4fca7
Show file tree

Hide file tree

Showing 5 changed files with 179 additions and 123 deletions.
diff --git a/cmake/docs.cmake b/cmake/docs.cmake
@@ -25,26 +25,47 @@ 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_docs_cmake target )
-    # Make `docs.cmake` show up in IDE/project
+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};cmake/docs.cmake"
+        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 - The KTX Library" )
+    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 )
@@ -76,7 +97,7 @@ function( CreateDocLibKTX )
         ktx_uint32_t numLevels\;                   \\
         ktx_uint32_t numLayers\;                   \\
         ktx_uint32_t numFaces\;                    \\
-        struct {                                  \\
+        struct {                                   \\
             ktxOrientationX x\;                    \\
             ktxOrientationY y\;                    \\
             ktxOrientationZ z\;                    \\
@@ -87,12 +108,11 @@ function( CreateDocLibKTX )
         ktx_size_t dataSize\;                      \\
         ktx_uint8_t* pData\;"
     )
-    set( DOXYGEN_GENERATE_TAGFILE ${docdest}/libktx.tag )
+    #set( DOXYGEN_GENERATE_TAGFILE ${docdest}/libktx.tag )
 
     doxygen_add_docs(
         libktx.doc
-        lib/mainpage.md
-        LICENSE.md
+        lib/libktx_mainpage.md
         include
         lib/astc_encode.cpp
         lib/basis_encode.cpp
@@ -110,29 +130,26 @@ function( CreateDocLibKTX )
         lib/writer1.c
         lib/writer2.c
     )
-    add_docs_cmake(libktx.doc)
+    add_docs_cmake_plus( libktx.doc pkgdoc/libktxDoxyLayout.xml )
 endfunction()
 
 # ktxtools.doc
-function( CreateDocKTXTools )
-    set( DOXYGEN_PROJECT_NAME "Khronos Texture Tools" )
+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_GENERATE_TAGFILE ${docdest}/ktxtools.tag )
+    set( DOXYGEN_TAGFILES ${docdest}/ktxpkg.tag=.. )
 
     doxygen_add_docs(
-        ktxtools.doc
-        tools/ktxinfo/ktxinfo.cpp
-        tools/ktx2check/ktx2check.cpp
-        tools/ktx2ktx2/ktx2ktx2.cpp
-        tools/ktxsc/ktxsc.cpp
-        tools/toktx/toktx.cc
+        tools.doc
         tools/ktx/ktx_main.cpp
         tools/ktx/command_create.cpp
         tools/ktx/command_encode.cpp
@@ -141,10 +158,33 @@ function( CreateDocKTXTools )
         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(ktxtools.doc)
+    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 )
@@ -154,29 +194,40 @@ function( CreateDocKTX )
     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 )
+    #set( DOXYGEN_TAGFILES ${docdest}/libktx.tag=libktx ${docdest}/ktxtools.tag=ktxtools )
 
     doxygen_add_docs(
         ktxpkg.doc
         pkgdoc/pages.md
-        TODO.md
-        interface/js_binding
-        ALL
+        LICENSE.md
+        #RELEASE_NOTES.md
     )
-    add_docs_cmake(ktxpkg.doc)
+    add_docs_cmake_plus( ktxpkg.doc pkgdoc/packageDoxyLayout.xml )
 endfunction()
 
 CreateDocLibKTX()
-CreateDocKTXTools()
+CreateDocTools()
+CreateDocJSWrappers()
 CreateDocKTX()
 
-add_dependencies( libktx.doc ktx_version )
-add_dependencies( ktxtools.doc libktx.doc )
-add_dependencies( ktxpkg.doc ktxtools.doc )
-
+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