Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-55139

Automatically generate code attributions in Qt documentation



    • Type: Task
    • Status: Closed
    • Priority: P2: Important
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: 5.8.0
    • Component/s: Documentation
    • Labels:


      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




      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


      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.


        No reviews matched the request. Check your Options in the drop-down menu of this sections header.



            kkohne Kai Köhne
            kkohne Kai Köhne
            0 Vote for this issue
            1 Start watching this issue



                Gerrit Reviews

                There are no open Gerrit changes