search

mozilla / cubeb

Cross platform audio library
ISC License
439 stars 124 forks source link

build(docs): use doxygen_add_docs() #726

Open Tachi107 opened 1 year ago

Tachi107 commented 1 year ago

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/.

As another minor change, I've also associated the installed docs to the Documentation component, so that users can choose to install only them with cmake --install builddir --component Documentation.

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>