make doc will not regenerate docs when a file has been removed

[Peter]

I have the following case:

test_documentation.sh failed because I had file FOO.h in yat/utility that was not documented. Fine so I remove the file and issue make check again, with the same result. The reason is that test_documentation.sh issues an make html and html: depends on all its source files (*.h in yat/) and obviously none of them has been changed since last time docs were generated. Except that one file has been removed.

[Peter]

A first fix could be to modify doc targets to also depend on directories, for example, rather than only check time-stamp of files in yat/utility we could also check time-stamp of yat/utility.

[Peter]

(In [1905]) Revised make dependencies for generating doxygen docs (fixes #438 and #501).

In doxygen.config removed variables INPUT and FILE_PATTERN to avoid us from editing these values. The variables ignored in the new setup.

doc/Makefile includes a 'doxygen.mk' located in each of the directories with header files. This is similar to how Maefiles include files from '.deps/' to get dependencies for source and header files. The inclusion relies on an undocumented feature in Automake, but it should likely not be a problem with future versions of Automake as it has been frequently been mentioned as a solution on the automake mailing list.

These 'doxygen.mk' are generated during 'make all' in each of these directories; they are also updated during 'make {doc|html|dvi|ps|pdf}' in topdir and topdir/yat. This latter is to avoid situations in which doc/Makefile is corrupted because of missing include.

This implies that obscure things like make clean && cd doc && make doc will fail noisily.

One could let doc/Makefile go into yat/subdirs and create the doxygen.mk files but I don't like that kind of setup.

Another thought might be to have doxygen.mk removed during 'make distclean' rather than 'make clean'. Thoughts are welcome.