Decide on future technology for rendering help content

We should decide on the future stack for rendering help content.

Business Rationale

Helping the user with good documentation is an important part of Qt's user experience. Documentation does include overview documentation, tutorials, documentation for specific examples, as well as class, type and method documentation.

Most of our documentation is generated with the help of the qdoc toolchain, and made available in different places:

• Online Documentation
• Qt Assistant
• Qt Creator (Help Mode, tooltips)
• Qt Visual Studio Plugin ( to be clarified? )

We expect a typical user will use any combination of these:

• The online documentation is easy to reach and search in.

• The integration into Qt Creator is especially tailored to make the information readily available while working (by rendering tooltips and providing context sensitive help); this is especially relevant for the C++ class/function and QML Type documentation.

• Qt Assistant is used for people who don't use Qt Creator in offline scenarios, and is also something we provide as a solution to customers to render their content in. It furthermore serves as a standalone testbed for Qt Help.

Unfortunately we haven't been able to render the documentation in the same quality and with the same feature set across all places, which leads to a number of bug reports and complaints.

Changes in the rendering part also meant that the value of Qt Help / Qt Assistant as a solution for our customers has diminished [see xxx].

Requirements

We consider it important that the rendering of the documentation in all places is of good quality.

Differences in the rendering that are not based on the different use cases should be avoided.

We should aim also for a unified stack, instead of having different solutions for different platforms.

We consider it important to also provide a way to see documentation offline.

Current State

qdoc toolchain

qdoc can either generate DITA XML, or HTML. The DITA XML backend is not used by us, instead we solely rely on the HTML backend.

While the HTML generated by qdoc is a stable subset of HTML4, the generated documentation is further augmented by (CSS) styles and templates. To accommodate the different backends and use cases Qt currently provides three different output styles:

• online documentation
• offline documentation
• offline documentation (simple)

Last one is a stripped down version specifically for QTextEdit.

Note also that qdoc is not the only tool used to generate Qt help content (.qch files): There are also providers of documentation in .qch format, like https://en.cppreference.com/w/Cppreference:Archives.

Qt Assistant

Qt Assistant currently supports rendering with Qt WebKit and QTextBrowser. In our binary builds QTextBrowser is used. A patch for supporting rendering with Qt WebEngine was made, but never merged.

Qt Creator

Qt Creator supports rendering with QTextBrowser, Qt WebEngine, native browser (on macOS). In the binary packages QTextBrowser is used, except for macOS, where we use the native browser.

What's wrong with QTextBrowser?

Main problem with QTextBrowser is that it only supports a subset of HTML, and a small subset of the CSS 2.1 standard: QTCREATORBUG-15887, QTBUG-67439.

There are also bugs in the rendering that show up as artifacts, e.g. in the font rendering and in the box model. We have been fixing some of them, but there are still issues left, and adapting help and CSS to the restrictions and QTextBrowser has an inherent cost.

Proposal 1: Move to Qt WebEngine

Switch Qt Creator and Assistant to use Qt WebEngine.

Advantages

• Full HTML5 support
• Testbed for Qt WebEngine

Disadvantages

• Large memory footprint
• Large binary footprint
• Longer startup times
• More system library dependencies
• Not available on all toolchains (no Qt Assistant for MinGW, MSVC 2015 packages)
• Upstream project might have further restrictions on the target platform

Challenges

• How to handle (security) updates? Do we need to update Qt Creator then?
• Uses Qt Quick SceneGraph for rendering, which is challenging because selecting the OpenGL backend also has an affect on other part of Qt Creator (QML Profiler, Welcome screen ..)

Effort: Medium

• Qt Assistant would need a plugin system (to avoid qttools->qtwebengine dependency)
• Qt WebEngine would need to move away from Qt Quick SceneGraph, or the scenegraph would need per-instance settings regarding whether to use OpenGL or not
• Changes required related to packaging Qt Creator and tools

Proposal 2: Use local browser

Drop Qt Assistant, Qt Creator Help mode. Instead show anything but tool-tips in an external browser window, e.g. by running a local web server.

Advantages

• No additional dependency (there will be always a system browser)
• (Possible) testbed for Qt WebServer

Disadvantages

• Qt Assistant gets removed also for our developer offering
• Display of help content inside Qt Creator not possible anymore

Challenges

• Unclear how well an integration would work in practice (e.g. how to avoid opening a new tab for each request, e.g. on context help)

• Testing such a combination might be challenging

Effort: Would need to be studied

Proposal 3: Use local browser engine

Use the system browser engine in both Assistant and Qt Creator, e.g. via Qt WebView.

Advantages

• No additional dependency / overhead
• Would increase use cases of Qt WebView

Disadvantages

• macOS backend for Qt WebView is there, but has some issues
• Windows backend possible, but not there yet
• There's no system browser on Linux

Effort: Medium-High

Proposal 4: Use new minimal renderer based on LiteHTML

Use a new HTML5 renderer based on LiteHTML

Advantages

• Overhead in terms of size and memory rather small
• Might be also a solution for other customer use cases

Disadvantages

• Feature set of LiteHTML is not well defined (but seems better than QTextBrowser)

Challenges

• Should such a renderer be a (non)-public class in qt help, a qt-labs module .... ?

Effort: Medium

• Write QPainter based renderer for LiteHTML