lots of Classes missing from docs (e.g. QFileInfo)

[michael]

[Impact]
The packaged Qt documentation, which can be viewed in browser (qt*-doc-html packages) or in Qt Assistant (qt*-doc packages) is missing all documentation generated from C++ files. Only the static text is present.

Qt is split by many modules (qtbase, qtdeclarative, qtwebengine, etc.).

To properly fix this bug, we need changes in qtbase and qttools modules. In addition, I will be uploading a no-change rebuild of qtdeclarative module to demonstrate that the fixes work.

If requested, I can also upload no-change rebuilds of some other modules to get their -doc packages properly regenerated.

[Test Case]
For qtbase5-doc-html:
1. Install qtbase5-doc-html package.
2. Make sure /usr/share/qt5/doc/qtcore/qobject.html is present.

For qtdeclarative5-doc-html:
1. Install qtdeclarative5-doc-html package.
2. Make sure /usr/share/qt5/doc/qtquick/qquickwidget.html is present.

[Regression Potential]
The proposed change in qtbase is affecting only builds of Qt modules documentation. So the worst thing it can do is breaking the build of -doc packages in other Qt modules. However, as confirmed by qtdeclarative example, it makes things only better, not worse.

The proposed change in qttools can affect more packages. It can result in qdoc passing more -isystem flags to clang code analyzer. I am not aware of negative consequences of this, but if they happen, these consequences will be limited to potential build failures or wrong documentation contents.

[Other Info]
Description of the fix:

qdoc is a tool that parses C++ source files and generates documentation from them. Recently, qdoc began using clang instead of its own C++ parser. Clang needs the C++ standard library to work. Starting with llvm-toolchain 1:7~+rc1-1~exp2, the GCC C++ standard library is no longer on clang’s default search paths, so we need to pass it explicitly as -I flag. The proposed qtbase patch (qdoc_default_incdirs.diff) does that.

That patch fixes documentation build for qtbase, but for other modules there is another problem. The Qt headers are installed into /usr/include/<triplet>/qt5 directory, but it is also not on Clang default search path. qmake passes these directories as -isystem flags, but qdoc ignores -isystem by default, unless it is built with QDOC_PASS_ISYSTEM defined. So the proposed change in qttools is building with this define.

[Original Description]
The Qt offline documentation for cosmic is incomplete. In fact there's virtually no content what so ever. It would be easier I think to list what actually got picked up that what was missed.

[Dmitry Shachnev (mitya57)]

This is a bug in qdoc generator (built from qttools-opensource-src) and in qtbase5-doc-html binary package. Re-assigning accordingly.

[Adam Conrad (adconrad)]

An upload of qtbase-opensource-src to cosmic-proposed has been rejected from the upload queue for the following reason: "Per our IRC discussion, this should be fixed in the buggy tool, not the package that surfaced the bug.".

[Dmitry Shachnev (mitya57)]

This needs fixes in both qtbase and qttools. In addition, I will upload a no-change rebuild of qtdeclarative to demonstrate that the fix works.

Updating the description accordingly.

[Launchpad Janitor (janitor)]

This bug was fixed in the package qtbase-opensource-src - 5.11.2+dfsg-7ubuntu1

---------------
qtbase-opensource-src (5.11.2+dfsg-7ubuntu1) disco; urgency=medium

  * Merge from Debian Sid. Remaining changes:
    - Add arm64 to the architectures that GLES is enabled on.
    - Drop build dependency on libpcre2-dev which is in Universe; configure
      without -system-pcre.

 -- Rik Mills <email address hidden> Mon, 19 Nov 2018 15:49:12 +0000

[Launchpad Janitor (janitor)]

This bug was fixed in the package qttools-opensource-src - 5.11.2-5

---------------
qttools-opensource-src (5.11.2-5) unstable; urgency=medium

  * Build qdoc with QDOC_PASS_ISYSTEM defined. This is needed because qmake
    passes Qt include directories as -isystem flags, not as regular -I.
    See QTBUG-70896, LP: #1799111.

 -- Dmitry Shachnev <email address hidden> Thu, 15 Nov 2018 11:03:30 +0300

[Dmitry Shachnev (mitya57)]

The latest qtdeclarative build in Disco contains the properly built documentation, so marking this bug as fixed there.

I am working on a backport to Cosmic now.

[Launchpad Janitor (janitor)]

Status changed to 'Confirmed' because the bug affects multiple users.

[DesiOtaku (tej-ashok-shah)]

Do we have an ETA when the fix will be released to Cosmic?

[Dmitry Shachnev (mitya57)]

The packages are waiting in the review queue since November 27th: https://launchpad.net/ubuntu/cosmic/+queue?queue_state=1. Now it’s up to SRU team to review them.

[Dmitry Shachnev (mitya57)]

Verifying in a cosmic chroot:

# apt install qtbase5-doc-html qtdeclarative5-doc-html
[...]
Get:1 http://archive.ubuntu.com/ubuntu cosmic-proposed/universe amd64 qtbase5-doc-html all 5.11.1+dfsg-7ubuntu2 [22.1 MB]
Get:2 http://archive.ubuntu.com/ubuntu cosmic-proposed/universe amd64 qtdeclarative5-doc-html all 5.11.1-6build1 [11.6 MB]
[...]
# dpkg -L qtbase5-doc-html | grep /usr/share/qt5/doc/qtcore/qobject.html
/usr/share/qt5/doc/qtcore/qobject.html
# dpkg -L qtdeclarative5-doc-html | grep /usr/share/qt5/doc/qtquick/qquickwidget.html
/usr/share/qt5/doc/qtquick/qquickwidget.html

Note that presence of the file in qtdeclarative5-doc-html is a verification for qttools-opensource-src too.

[Łukasz Zemczak (sil2100)]

The pending-sru page reports that there are some kdeconnect (and a few other) autopkgtest regressions for the qtbase upload. I have re-ran most of them, but could someone take a look and check why they suddenly fail?

[Dmitry Shachnev (mitya57)]

That definitely is not related to my changes. However, it could be caused by the fact that qtbase is rebuilt against new OpenSSL or something like that. I found a similar bug in Debian: https://bugs.debian.org/907339.

Let’s see if retrying the tests against kdeconnect 1.3.3 (which just migrated to -updates) fixes it.

[Dmitry Shachnev (mitya57)]

@Łukasz: kdeconnect tests failures is a race condition in tests, not a real bug.

This patch (which is applied in Disco) https://salsa.debian.org/qt-kde-team/extras/kdeconnect/blob/master/debian/patches/ssl_socket_race_fix.diff would fix it. But as it’s a bug in tests and not in real code, I would just ignore it.

[Łukasz Zemczak (sil2100)]

Ok, makes sense. I'll ignore the failure and release the packages. Please note that I will not add a hint for the kdeconnect failures as otherwise, because it's a race-condition in one test only, we might miss some real regressions in future uploads that would trigger those tests.

[Launchpad Janitor (janitor)]

This bug was fixed in the package qttools-opensource-src - 5.11.1-5ubuntu1

---------------
qttools-opensource-src (5.11.1-5ubuntu1) cosmic; urgency=medium

  * Build qdoc with QDOC_PASS_ISYSTEM defined. This is needed because qmake
    passes Qt include directories as -isystem flags, not as regular -I (LP:
    #1799111).

 -- Dmitry Shachnev <email address hidden> Mon, 26 Nov 2018 11:48:25 +0300

[Łukasz Zemczak (sil2100)]

The verification of the Stable Release Update for qttools-opensource-src has completed successfully and the package has now been released to -updates. Subsequently, the Ubuntu Stable Release Updates Team is being unsubscribed and will not receive messages about this bug report. In the event that you encounter a regression using the package from -updates please report a new bug using ubuntu-bug and tag the bug report regression-update so we can easily find any regressions.

[Launchpad Janitor (janitor)]

This bug was fixed in the package qtbase-opensource-src - 5.11.1+dfsg-7ubuntu2

---------------
qtbase-opensource-src (5.11.1+dfsg-7ubuntu2) cosmic; urgency=medium

  * Add a patch to pass default include directories to qdoc (LP: #1799111).

 -- Dmitry Shachnev <email address hidden> Fri, 02 Nov 2018 14:41:35 +0300

[Launchpad Janitor (janitor)]

This bug was fixed in the package qtdeclarative-opensource-src - 5.11.1-6build1

---------------
qtdeclarative-opensource-src (5.11.1-6build1) cosmic; urgency=medium

  * No-change rebuild against updated qtbase and qttools to get the
    documentation packages properly regenerated (LP: #1799111).

 -- Dmitry Shachnev <email address hidden> Mon, 26 Nov 2018 12:30:29 +0300