Automatically updating Doxygen documentation and making it readily available to users with CMake

Question

I have worked on multiple C++ libraries that are built with CMake and run Doxygen to generate HTML documentation. In every one of these libraries, the documentation get's built into an "html" folder in the CMake "build" directory and never gets looked at by anyone.

Because let's be honest, most people don't like to read documentation at all - let alone search for it.

This leads to a few questions:

1. Is there a standard location to install the documentation once it is built where it makes it very clear to users that documentation is available for a library?

2. How can I ensure that every time my library is built, the documentation will be automatically updated and installed in this standard location?

3. Is there any standard way to keep past versions of documentation for reference in case someone is using an earlier version of the library?

Answer 1

1) According to the Filesystem Hierarchy Standard

4.11.3. Specific Options
The following directories, or symbolic links to directories, must be in /usr/share, if the corresponding subsystem is installed:
Directory Description
...
doc Miscellaneous documentation (optional)

2) I would say, you can add to the install target a command to copy the doxygen in prefix/usr/share/doc

Also having the doxygen in the build dir first, seems ok IMHO.

3) Usually with a distro having a package manager you can create a doc package so user who want "past" doc just need to get the package doc having the same revision than the binary package...

note: on Archlinux doc is shipped with the library, on Debian like you have package-doc, same for homebrew IIRC

note: you can also configure doxygen so the error message generated can be parsed by your ide (e.g. QtCreator) like regular gcc error so you can see them in the error log at each build.