View source for QtCS2021 - Documentation test builds in the CI system

[[Category:QtCS2021]]

==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
**Background
***Time consuming: We spend an unreasonable amount of time cleaning up QDoc warnings.
***No safety net: Warnings enter the code base, cleanup happens after-the-fact.
***Monitoring: We track qdoc warnings and how they develop over time. Is this an effort better spent doing something else?
***COIN: CI blocks compiler warnings, why not QDoc warnings?
**Proposal
***Provision the tools we need in one CI configuration.
***Enforcement per module.
***Dealing with special cases.
**The nitty-gritty
***Tools provisioning: https://codereview.qt-project.org/c/qt/qt5/+/331624<nowiki/>
***QDoc-specific instructions during testing: https://codereview.qt-project.org/c/qt/qtbase/+/331625<nowiki/>
***QDoc warning documentation: https://doc.qt.io/qt/qdoc-warnings.html<nowiki/>

*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.