Hi, A while ago I proposed to generate 3rd party code attributions out of files that are right beside the code, instead of hand-editing 3rdparty.html in qtdoc. I've now a set of patches that are IMO worth to take a look at (also because FF for 5.8 is coming ;)
# 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 'licensescanner' 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 (btw thanks for the pointer!). 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 licensescanner to generate other formats, too. The current format is documented in https://wiki.qt.io/Qt_attribution.json . 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{attributions}, \generatelist{annotatedattributions} commands. # Patches qttools patches (licensescanner, 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. Regards Kai -- Kai Köhne, Senior Manager R&D | The Qt Company The Qt Company GmbH, Rudower Chaussee 13, D-12489 Berlin Geschäftsführer: Mika Pälsi, Juha Varelius, Mika Harjuaho. Sitz der Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, HRB 144331 B _______________________________________________ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
