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

Automatically generate code attributions in Qt documentation

    XMLWordPrintable

    Details

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

      Description

      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

      {attributions}

      , \generatelist

      {annotatedattributions}

      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.

        Attachments

        For Gerrit Dashboard: QTBUG-55139
        # Subject Branch Project Status CR V

          Activity

            People

            Assignee:
            kkohne Kai Köhne
            Reporter:
            kkohne Kai Köhne
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved:

                Gerrit Reviews

                There are no open Gerrit changes