Skip to content

Commit

Permalink
build(docs): use doxygen_add_docs()
Browse files Browse the repository at this point in the history 
I had originally done this in #662, but never re-submitted it.
06aa271 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
    < <title>cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h File Reference</title>
    ---
    > <title>cubeb: include/cubeb/cubeb.h File Reference</title>
    87,92c87,92
    < <div class="center"><img src="cubeb_8h__incl.png" border="0" usemap="#a_2tmp_2tmp_8ils_at_y7fk0_2up_2cubeb_2include_2cubeb_2cubeb_8h" alt=""/></div>
    < <map name="a_2tmp_2tmp_8ils_at_y7fk0_2up_2cubeb_2include_2cubeb_2cubeb_8h" id="a_2tmp_2tmp_8ils_at_y7fk0_2up_2cubeb_2include_2cubeb_2cubeb_8h">
    < <area shape="rect" title="The libcubeb C API." alt="" coords="99,5,277,61"/>
    < <area shape="rect" title=" " alt="" coords="5,109,128,136"/>
    < <area shape="rect" title=" " alt="" coords="153,109,223,136"/>
    < <area shape="rect" title=" " alt="" coords="247,109,318,136"/>
    ---
    > <div class="center"><img src="cubeb_8h__incl.png" border="0" usemap="#ainclude_2cubeb_2cubeb_8h" alt=""/></div>
    > <map name="ainclude_2cubeb_2cubeb_8h" id="ainclude_2cubeb_2cubeb_8h">
    > <area shape="rect" title="The libcubeb C API." alt="" coords="105,5,271,32"/>
    > <area shape="rect" title=" " alt="" coords="5,80,128,107"/>
    > <area shape="rect" title=" " alt="" coords="153,80,223,107"/>
    > <area shape="rect" title=" " alt="" coords="247,80,318,107"/>
    diff html_no_patch_dot/cubeb_8h__incl.map html_dot/cubeb_8h__incl.map
    1,5c1,5
    < <map id="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h" name="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h">
    < <area shape="rect" id="node1" title="The libcubeb C API." alt="" coords="99,5,277,61"/>
    < <area shape="rect" id="node2" title=" " alt="" coords="5,109,128,136"/>
    < <area shape="rect" id="node3" title=" " alt="" coords="153,109,223,136"/>
    < <area shape="rect" id="node4" title=" " alt="" coords="247,109,318,136"/>
    ---
    > <map id="include/cubeb/cubeb.h" name="include/cubeb/cubeb.h">
    > <area shape="rect" id="node1" title="The libcubeb C API." alt="" coords="105,5,271,32"/>
    > <area shape="rect" id="node2" title=" " alt="" coords="5,80,128,107"/>
    > <area shape="rect" id="node3" title=" " alt="" coords="153,80,223,107"/>
    > <area shape="rect" id="node4" title=" " alt="" coords="247,80,318,107"/>
    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
    < <title>cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h Source File</title>
    ---
    > <title>cubeb: include/cubeb/cubeb.h Source File</title>
    diff html_no_patch_dot/dir_4a77ea686d101b1caa0240510cb36860.html html_dot/dir_4a77ea686d101b1caa0240510cb36860.html
    8c8
    < <title>cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb Directory Reference</title>
    ---
    > <title>cubeb: include/cubeb Directory Reference</title>
    75c75
    < <div class="center"><img src="dir_4a77ea686d101b1caa0240510cb36860_dep.png" border="0" usemap="#adir__4a77ea686d101b1caa0240510cb36860__dep" alt="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb"/></div>
    ---
    > <div class="center"><img src="dir_4a77ea686d101b1caa0240510cb36860_dep.png" border="0" usemap="#adir__4a77ea686d101b1caa0240510cb36860__dep" alt="include/cubeb"/></div>
    diff html_no_patch_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.map html_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.map
    1c1
    < <map id="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb" name="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb">
    ---
    > <map id="include/cubeb" name="include/cubeb">
    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
    < <title>cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include Directory Reference</title>
    ---
    > <title>cubeb: include Directory Reference</title>
    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
    < <li>/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    ---
    > <li>include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    diff html_no_patch_dot/structcubeb__device__collection.html html_dot/structcubeb__device__collection.html
    100c100
    < <li>/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    ---
    > <li>include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    diff html_no_patch_dot/structcubeb__device__info.html html_dot/structcubeb__device__info.html
    147c147
    < <li>/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    ---
    > <li>include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    diff html_no_patch_dot/structcubeb__stream__params.html html_dot/structcubeb__stream__params.html
    167c167
    < <li>/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    ---
    > <li>include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
  • Loading branch information
@Tachi107
Tachi107 committed Sep 25, 2022
1 parent 93d1fa3 commit 219cd4f
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 18 deletions.
19 changes: 13 additions & 6 deletions CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
12 changes: 0 additions & 12 deletions docs/Doxyfile.in
View file

This file was deleted.

0 comments on commit 219cd4f

Please sign in to comment.