[Development] Documenting 3rd party code Qt

Kai Koehne Kai.Koehne at qt.io
Wed Jul 20 13:13:39 CEST 2016


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


More information about the Development mailing list