From 219cd4f652560b9412c3482ecb6edddff47a0123 Mon Sep 17 00:00:00 2001 From: Andrea Pappacoda Date: Sun, 25 Sep 2022 13:47:11 +0200 Subject: [PATCH] build(docs): use doxygen_add_docs() I had originally done this in #662, but never re-submitted it. 06aa271e5bca1a74692c8828ad8585dd9598e092 reminded me that I should also include Doxygen documentation in the Debian package, so I took a bit of time to re-prepare this patch. Using CMake's doxygen_add_docs() isn't only more concise and idiomatic, it also solves actual issues of Doxygen-generated documentation. Without this patch, the generated docs include an absolute path of the build directory; apart from being ugly, it also creates issues with reproducibility, as it is required to rebuild the package in the same exact directory to get a bit-by-bit identical copy of the package. CMake is able to work around this Doxygen quirk, and the generated HTML only includes relative paths. The documentation gets now output to build/html/ instead of build/docs/html/. Here's a full diff of the generated output before and after applying this patch: diff html_no_patch_dot/cubeb_8h.html html_dot/cubeb_8h.html 8c8 < cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h File Reference --- > cubeb: include/cubeb/cubeb.h File Reference 87,92c87,92 <
< < < < < --- >
> > > > > diff html_no_patch_dot/cubeb_8h__incl.map html_dot/cubeb_8h__incl.map 1,5c1,5 < < < < < --- > > > > > diff html_no_patch_dot/cubeb_8h__incl.md5 html_dot/cubeb_8h__incl.md5 1c1 < 80f3c1becd2984dea59dbcc5f43d8bc7 \ No newline at end of file --- > bd73bf4d2f8603949fb7021f1b7e2758 \ No newline at end of file Binary files html_no_patch_dot/cubeb_8h__incl.png and html_dot/cubeb_8h__incl.png differ diff html_no_patch_dot/cubeb_8h_source.html html_dot/cubeb_8h_source.html 8c8 < cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h Source File --- > cubeb: include/cubeb/cubeb.h Source File diff html_no_patch_dot/dir_4a77ea686d101b1caa0240510cb36860.html html_dot/dir_4a77ea686d101b1caa0240510cb36860.html 8c8 < cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb Directory Reference --- > cubeb: include/cubeb Directory Reference 75c75 <
/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb
--- >
include/cubeb
diff html_no_patch_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.map html_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.map 1c1 < --- > diff html_no_patch_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.md5 html_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.md5 1c1 < d2b3a541ded19d569e3456d07b13bfca \ No newline at end of file --- > ba94d8d8e5033c1685cddf5e6ffcb5a1 \ No newline at end of file diff html_no_patch_dot/dir_d44c64559bbebec7f509842c48db8b23.html html_dot/dir_d44c64559bbebec7f509842c48db8b23.html 8c8 < cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include Directory Reference --- > cubeb: include Directory Reference Common subdirectories: html_no_patch_dot/search and html_dot/search diff html_no_patch_dot/structcubeb__device.html html_dot/structcubeb__device.html 90c90 <
  • /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h
    • --- >
  • include/cubeb/cubeb.h
    • diff html_no_patch_dot/structcubeb__device__collection.html html_dot/structcubeb__device__collection.html 100c100 <
  • /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h
    • --- >
  • include/cubeb/cubeb.h
    • diff html_no_patch_dot/structcubeb__device__info.html html_dot/structcubeb__device__info.html 147c147 <
  • /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h
    • --- >
  • include/cubeb/cubeb.h
    • diff html_no_patch_dot/structcubeb__stream__params.html html_dot/structcubeb__stream__params.html 167c167 <
  • /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h
    • --- >
  • include/cubeb/cubeb.h
    • --- CMakeLists.txt | 19 +++++++++++++------ docs/Doxyfile.in | 12 ------------ 2 files changed, 13 insertions(+), 18 deletions(-) delete mode 100644 docs/Doxyfile.in diff --git a/CMakeLists.txt b/CMakeLists.txt index 7ae58d44..d2b46b5b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -366,12 +366,19 @@ endif() find_package(Doxygen) if(DOXYGEN_FOUND) - configure_file(${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/docs/Doxyfile @ONLY) - add_custom_target(doc ALL - ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/docs/Doxyfile - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs - COMMENT "Generating API documentation with Doxygen" VERBATIM) - install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs/html/ TYPE DOC) + set(DOXYGEN_JAVADOC_AUTOBRIEF YES) + set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) + set(DOXYGEN_CASE_SENSE_NAMES NO) + set(DOXYGEN_SORT_MEMBER_DOCS NO) + set(DOXYGEN_QUIET YES) + set(DOXYGEN_WARN_NO_PARAMDOC YES) + set(DOXYGEN_GENERATE_HTML YES) + + doxygen_add_docs(doc "include/cubeb/" ALL + COMMENT "Generating API documentation with Doxygen" + ) + + install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ TYPE DOC) endif() if(BUILD_TESTS) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in deleted file mode 100644 index 8ec863be..00000000 --- a/docs/Doxyfile.in +++ /dev/null @@ -1,12 +0,0 @@ -PROJECT_NAME = @PROJECT_NAME@ -PROJECT_NUMBER = @PROJECT_VERSION@ -OUTPUT_DIRECTORY = . -JAVADOC_AUTOBRIEF = YES -OPTIMIZE_OUTPUT_FOR_C = YES -CASE_SENSE_NAMES = NO -SORT_MEMBER_DOCS = NO -QUIET = YES -WARN_NO_PARAMDOC = YES -INPUT = @CMAKE_CURRENT_SOURCE_DIR@/include/cubeb -GENERATE_HTML = YES -GENERATE_LATEX = NO