To reproduce the problem:
- download the lsstDoxygen package
- cd lsstDoxygen
- setup -r .
- # choose a package for which to generate docs. It takes a long time to generate docs for lsst_distrib whereas afw is fast and shows the problem, so I recommend afw, but meas_algorithms is another good choice
- setup afw
- makeDocs afw
The problem may be in how makeDocs processes the INPUT line of the package's doxygen config is handled. For the afw package I observe that the INPUT line contains several paths (each path is surrounded by double quotes separated from the next by spaces), but the code tries to process all of them as one. As a consequence the code never looks for the main page in the doc directory, but instead only looks in the src directory (the path to src is the last entry on the INPUT line). If so, one fix is to split the INPUT line and process each path separately. Another is to write multiple INPUT lines, one per path (if Doxygen supports that). Splitting the line will take a bit of work, since the code should support spaces within the paths. It also raises the question of how this code ever worked (perhaps the config files used to have multiple INPUT lines?).