Feature #18637

Provide a macro for installing documentation together with the source

Added by Gianluca Petrillo over 3 years ago. Updated about 3 years ago.

Target version:
Start date:
Due date:
% Done:


Estimated time:
4.00 h
Spent time:


Within LArSoft effort in promoting code documentation, we want to offer the easiest way possible to distribute documentation.
It happens that the documentation of a feature does not fit well with being shipped in any specific source code file, but it rather fits into its own file, in the directory with the code supporting the feature. Popular formats are plain text (*.txt), README files (`README*`), LaTeX sources (*.tex) and markdown documents (*.md and *.markdown).
Also, for doxygen integration it is useful to write doxygen commands into their own file. While these are valid C++ source and could be saved in a header file, in order not to create confusion by the build system and the users it is better to have them in their own file type (*.dox).

LArSoft in particular generates the documentation from the installed UPS products, therefore it is necessary for these files to be installed in the source tree of the UPS product.
This is possible writing a couple of lines of CMake, like

file(GLOB DocList
     *.txt *.tex *.md *.markdown *.dox README*
install_source(EXTRAS ${DocList})
but that's not anything we can expect normal users to write.

This request is for a new macro install_sourcedoc() which does this out of the box. In alternative, those patterns may be added to install_source() itself (that would also have the good effect of finally including CMakeLists.txt...), maybe via an option like WITHDOCS.

Related issues

Related to LArSoft - Feature #18708: reconsider the doxygen buildAssigned01/09/2018


#1 Updated by Lynn Garren over 3 years ago

  • Status changed from New to Feedback

Gianluca, can you point us to some places in the larsoft code where this macro would be used?

#2 Updated by Lynn Garren over 3 years ago

  • Status changed from Feedback to Assigned
  • Assignee set to Lynn Garren
  • Estimated time set to 4.00 h

We will add README* and *.md to install_source. We observe that users are already comfortable adding extra files to install source, so it would seem to be no problem to add a few extra document files when necessary.

Also, we wish to point out that the purpose of install_source is to provide generated code along with the regular source code for debugging purposes. Without this facility, generated code is unavailable in the distributed product.

We suggest that perhaps larsoft can make the doxygen build when cutting a release instead of with the current process. We are, however, aware that this is a non-trivial change which will require some design effort.

#3 Updated by Lynn Garren over 3 years ago

#4 Updated by Lynn Garren over 3 years ago

  • Status changed from Assigned to Resolved
  • % Done changed from 0 to 100

The update to install_source is implemented in cetbuildtools v6_01_01. The next release of larsoft will include cetbuildtools v6_01_01 and appropriate changes in the CMakeLists.txt files.

#5 Updated by Lynn Garren over 3 years ago

Late breaking change: install_source now also looks for *.dox

#6 Updated by Lynn Garren about 3 years ago

  • Status changed from Resolved to Closed

Also available in: Atom PDF