doxygen documentation links to absolute paths

Issue created by migration from Trac.

Original creator: @svigerske

Original creation time: 2012-02-05 18:21:36

Assignee: @svigerske

Version: 0.7

The new doxygen documentation that uses tag files to connect the documentation of different projects seem to produce absolute paths, which are bad when copying the docu to the webserver.

E.g., the link for OsiClpSolverInterface at http://www.coin-or.org/Doxygen/Cbc/inherits.html points to http://www.coin-or.org/home/coin/SVN-release/Cbc-2.7.5/Clp/doxydoc/html/classOsiClpSolverInterface.html.

It's not clear yet if this is a build system issue or a problem with the scripts that automatically generate and copy the documentation, or both.

Some comments from Lou:

What happens at present is that doxygen documentation is built in the build directory. For classic package Foo, with externals Ext1, Ext2, documentation is built in

  ${build}/Ext1/doxydoc/html
  ${build}/Ext2/doxydoc/html        <-- external's doxydoc directory
  ${build}/doxydoc/html             <-- package doxydoc directory

Installation installs only the package doxydoc/html directory into ${install}/share/coin/doc/Foo/doxydoc/html. This works well for the split configuration but is arguably wrong for the classic package, because the installed doxydoc will reach back to the build directory for each external's doxydoc. But it's only a problem if the build directory disappears. I haven't worried too much about it on the theory that we're headed towards separate packages, which will replicate the split configuration.

The DOXYGEN configure macro produces absolute paths. This could possibly be fixed, but it'd be a bit painful.

The DOXYGEN configure macro looks for tag files first in the build directory, then in the install directory.

The advantage to this scheme is that source files of externals are processed exactly once (they are excluded in the package's doxygen.conf file, hence not processed a second time when the package doxydoc is built). A second advantage is that it works for the split configuration (packages checked out without externals, connected through the install directory).

It would be nice to running doxygen unless source actually changes, but the current directory structure makes that more or less impossible (would require enumerating source files at a higher level in the makefile hierarchy than is done at present).

From what Laci and Matt have said, the problem would most likely be that the absolute path to the build directory has changed between the old and new server, or the build directory is absent.

coin-or-tools / BuildTools

doxygen documentation links to absolute paths #96