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

[Alan W. Irwin]

On 2019-02-20 17:52-0500 Timothy Wrona wrote:

> 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 put the documentation once it is built
>   where it makes it very clear to the users of a library 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 placed 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?
>
> I have also posted this question on stack overflow. If you would like, you
> can answer there instead because it may help a wider audience:
> https://stackoverflow.com/questions/54796513/automatically-updating-doxygen-documentation-and-making-it-readily-available-to

I am not aware of any standard responses to your 3 questions above.

What I do for a couple of my projects that have doxygen-generated
documentation is I have a special custom command/target that copies
the doxygen-generated documentation from the build tree back to a
special directory in the source tree, and I only invoke that target if
I am creating a source tarball.  And similarly for DocBook-generated
documentation.  Furthermore, I configure my VCS in each case to ignore
those generated directories in the source tree so there are no VCS
complications, yet tarball users get a chance to access the generated
documentation.

Of course, if someone here has a better or more standardized scheme, I would like to hear it.

Alan
__________________________
Alan W. Irwin

Programming affiliations with the FreeEOS equation-of-state
implementation for stellar interiors (freeeos.sf.net); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________