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

[Raymond Wan]

Hi Timothy,

This is not something I'm very familiar with, but maybe I 
can still add a little to the discussion by answering both 
of your messages together.


On 21/2/2019 10:18 PM, Timothy Wrona wrote:
> Perhaps there is a standard location to "install" the 
> documentation when running the install command for a project?
> 
> Either way having it as an "index.html" file somewhere on 
> the hard-disk is not very intuitive. It would make much more 
> sense for it to be on a web server where you can access it 
> with a sensible URL.


You're right that it isn't intuitive, but then you're 
assuming that users will all install a (Apache, etc.) web 
server.  And many users do not.

If you're doing cross-platform development, then I am fairly 
sure that most of the people I know who use Microsoft 
Windows do not install a web server.

On my Ubuntu-based computer, I have installed a local 
version of the Boost library.  The HTML documentation is 
installed in:  $BOOST_ROOT/doc/html/ .  In my case, 
$BOOST_ROOT is /usr/local/boost_<version>/, but some people 
might install it in /opt, for example.

As for your 3 questions, I don't know the definitive answer 
but my gut feeling is:


>      >   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?


For packages installed using Ubuntu's package management 
system, documentation tends to go to /usr/share/doc/ or 
/usr/share/man/.  But I'm sure the path is different for 
CentOS, RedHat, etc.

If you're not installing software through a package manager, 
then the documentation probably goes into /usr/local or /opt 
(See: 
https://unix.stackexchange.com/questions/11544/what-is-the-difference-between-opt-and-usr-local).

For software that I've developed myself, I've placed the 
documentation together with the software, similar to the 
Boost library.  That is, within the root directory, I threw 
it into a directory called doc/.  If sysadmin access is 
required and it goes into /usr/local/<software>/, then like 
Boost, it would go inside that directory.

With other people's programs that I've downloaded myself, I 
normally look in the root directory (of that program) for a 
doc/ directory too.  So, perhaps the answer to your question 
about "standard location" is to just ask yourself if your 
role was reversed -- i.e., you're just a user -- where would 
you look for documentation?


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


Since this is your software and you wrote the CMake file, as 
long as you've defined and then fixed the installation 
target from version to version, then it should be ok.

I don't know what kind of automation you were looking for. 
Someone still has to do a "cmake ..; make; make install" or 
something like that.  You're not talking about automation 
along the lines of some cron job, are you?


>      >   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 think when you've asked "standard way", it sounds like 
you're looking for Doxygen and/or CMake having standardized 
the location.  But, based on my examples above, it seems it 
is OS dependent.

And it depends whether you're distributing the source files 
or the binaries only (i.e., like an Ubuntu/Debian .deb 
package).  In the case of the former, you've defined it 
using your CMake file.  In the latter case, you've compiled 
it and then wrote some instructions for Debian's package 
management software so that the documentation goes into 
/usr/share/doc, /usr/share/man/, etc.

Just my 2 cents...I'm happy to hear what others think.

Ray