QtCS2021 - Documentation test builds in the CI system

Session Summary

Every release of Qt brings with it a lot of "fire fighting" in terms of getting rid of QDoc's warnings across all modules. We propose to block changes that introduce QDoc warnings in CI. This is a session to discuss the proposed solution to the problem.

Session Owners

• Paul Wicking / Topi Reiniö (documentation.infrastructure@qt.io)

Notes

• Quick presentation by Topi and Paul.
• Per repo only, warnings for cross-linking references will be disregarded for technical reasons.
• One Ubuntu configuration only, as that's where release docs are built.
• Per module control, meaning modules can be excluded in special cases.

Discussion

• Enforcing no warnings would be good; potential problem: introducing new C++ standard features where QDoc struggles, for examples (e.g. when C++17 was introduces with Qt 6). What happens when C++20 shows up in Qt?
  • Possibly port QDoc from C-based clang API to C++-based API
  • Intention is to support development,
• Effort needed from doc team and CI team? CI system?
  • Patches in Gerrit are in good shape, might need some further support from the CI team.
  • Integration times extended by the doc build time required for each repo. E.g. qtbase adds maybe as much as 10 minutes (best guess).
  • Might run in parallel and not add integration time at all.
• Should doc builds run early to fail integrations early?
  • Play around with alternatives to provide quick feedback.