Automatically generate code attributions in Qt documentation

Information Flow

Every 3rd party code in our repositories should get a qt_attribution.json file containing metadata about the code. When the documentation of a module is built, a new tool qtattributionscanner is automatically run by qmake that scans the sources for qt_attribution.json files, and generates a .qdoc file with pages for every attribution it finds. An overview of the attributions is shown on each modules entry page. Finally, the current 3rdparty overview page should be automatically generated from all modules' attribution pages.

File Format

I had a look at SPDX, README.Chromium, debian/copyright. In the end I went for a custom format, because they all seem to not quite fit for our use case. Anyhow, it's easy to extend qtattributionsscanner tool to generate other formats, too.

The current format is documented in https://wiki.qt.io/Qt_attribution.json .

Also, it will be part of QUIP-4.

Real-life examples for qtbase can be found in https://codereview.qt-project.org/#/c/160970/ .

QDoc Extension

To be able to document and structure the 3rd party content I introduced a new 'attribution' attribute to qdoc's \page command, and added \generatelist

, \generatelist

commands.

Patches

qttools patches (qtattributionsscanner, qdoc modifications): https://codereview.qt-project.org/#/q/status:open+project:qt/qttools+branch:dev+topic:3rdparty,n,z
qtbase patches (qt_attributions.json files, build integration, overview pages): https://codereview.qt-project.org/#/q/status:open+project:qt/qtbase+branch:dev+topic:3rdparty,n,z
qtdoc patch (for general overview page): https://codereview.qt-project.org/#/q/status:open+project:qt/qtdoc+branch:dev+topic:3rdparty,n,z

FAQ

Q: Why do we need such an elaborate setup? Wouldn't it be easier to just write .qdoc files?

Keeping the 'documentation' close to the actual sources hopefully makes sure they're up to date and complete. Admittedly we could also just have .qdoc files right beside each code snipped, and include this one. In the future I'd like to extend the tool though so that attribution information (say HTML) for an app bundling Qt can be generated. The qt_attribution.json file could also be used as input to 3rd party code scanners popular in the industry, or used as a source for generating SPDX files ... Keeping the metadata outside of .qdoc makes this a lot easier.

Q: What about 3rd party code in tests/examples ...?

I think they should get a qt_attribution.json file too. We have to mark though what actually ends up in the Qt libs, and what only ends up in tests / build system / host tools ... I'm still contemplating how to best document this in the qt_attribution.json file.