QDocPreview

Live preview and linting for QDoc documentation — the Markdown-preview experience, for .qdoc files, .qdocinc fragments, and QDoc comments in C++ and QML sources.

How to use

Open a file, press Cmd+K V (Ctrl+K V), and the rendered documentation appears beside the editor and updates as you type.

You can also open the preview by clicking the Preview button, the same way you would open the Markdown preview:

You need neither the qdoc binary nor a documentation build: the extension reads your .qdocconf and renders straight from the file you are editing.

What it does

• Renders while you type, side by side, following the editor's color theme.
• Handles every kind of QDoc file: .qdoc pages, QDoc comments in C++ and QML sources, and .qdocinc fragments.
• Reads your .qdocconf so \image, \snippet, \include and macros such as \macos and \QtVersion resolve the way they will in the real build.
• Lints your markup in the Problems panel.
• Scroll sync — the preview follows the cursor, but only when it moves to a different comment. Double-click the preview to jump back to the source.
• Stays dormant in unrelated projects: it activates only where there is something Qt-shaped to work on.

Linting

Every check is a rule with a level you can change, so one noisy check can be silenced without losing the rest. The rule id appears beside each entry in the Problems panel, and the markup is marked in the preview where the problem occurs.

It reports:

• Unknown commands and undefined macros.
• Broken file references: images outside imagedirs, snippet files that do not exist, snippet markers that are absent, unresolvable \include targets.
• Problems in the .qdocconf itself, reported against the configuration file on the offending line, and listed in the preview's status bar.
• Unterminated constructs — a missing }, \endlist, \endcode, \endtable.
• \li outside a \list or \table, and stray \end… commands.
• Unrecognised \list style hints.
• \sa entries not separated by commas, \a naming something absent from the signature, \sa pointing at the thing being documented.
• A \brief that does not end with a full stop.
• Comments with no topic command, which QDoc also warns about.
• Images with no textual description.
• Deprecated commands such as \bold and \i.

Set a rule to off in qdocPreview.diagnostics.rules to silence it, or turn qdocPreview.diagnostics.enabled off for the lot. The setting's description lists all 25 rules, grouped by their default level.

Warnings your .qdocconf silences through spurious are still shown, one level quieter and labelled — the aim is documentation in good order rather than a quiet build. qdocPreview.diagnostics.suppressedByConfig changes that.

Installation

Download the latest .vsix from the Releases page, then in VS Code: Extensions → ⋯ → Install from VSIX…

Setup

After installing, set these settings:

qdocPreview.qtInstallDocs

Every module's .qdocconf includes Qt's global configuration, which is where the macros come from, so the extension needs to know where that is. Point this at <qt5.git repo>/qtbase/doc/.

Point it at your source tree, not an installed Qt. An installed Qt carries the macro set of the release it came from, so it reports problems your sources do not have.

qdocPreview.configVars

When the documentation is being built, some of the variables are resolved by CMake. qdocPreview.configVars lists the variables a preview cannot know: QT_VERSION, BUILDDIR, and so on. They default to empty, and nothing is reported about them — fill one in to see its real value. QT_VER and QT_VERSION_TAG are derived from QT_VERSION when you do not set them.

qdocPreview.roots

Limits where the extension activates. Entries may be absolute paths, paths relative to a workspace folder, or globs.

Example:

C:/sources/qt5/**                       (Windows)
/Users/myusername/sources/qt5/**        (macOS and Linux)

Left empty, QDocPreview activates in any workspace folder containing at least one .qdocconf, and stays dormant everywhere else.

All settings

Image descriptions

qdocPreview.altText.display decides what a sighted reader sees. The alt attribute is written in every mode, since that is what screen readers use:

An image with no description shows a no alt text marker and produces a warning. QDoc's own check is opt-in per module via reportmissingalttextforimages, which most Qt modules do not set — alt text is expected regardless, so the warning is not gated on it. Silence it with "missing-alt-text": "off" in qdocPreview.diagnostics.rules.

This image shows how the image caption is rendered by default:

Commands

Every command is under the QDocPreview: prefix in the Command Palette.

Contributing

Bug reports and patches are welcome. CONTRIBUTING.md explains the code layout, how to run the tests, and how to package the extension — no dependencies and no build step, only Node.js.