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

From the Marketplace: search for QDocPreview in the Extensions view (Cmd+Shift+X / Ctrl+Shift+X) and select Install, or install it from the Visual Studio Marketplace page.

From a .vsix file: download the latest release from the Releases page, then in VS Code: Extensions → ⋯ → Install from VSIX… Useful where the Marketplace is unreachable, or to try a specific version.

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

Setting	Default	Meaning
qdocPreview.roots	[]	Folders where the extension is active. Empty means any folder with a .qdocconf.
qdocPreview.qtInstallDocs	""	Value for $QT_INSTALL_DOCS.
qdocPreview.configVars	the build's variables, empty	Values for .qdocconf variables the build supplies, such as QT_VERSION.
qdocPreview.diagnostics.enabled	true	Report problems at all.
qdocPreview.diagnostics.rules	{}	Level per rule: off, hint, info, warning, error. 25 rules; see the setting's description.
qdocPreview.diagnostics.suppressedByConfig	"downgrade"	What to do with warnings the .qdocconf silences via spurious.
qdocPreview.altText.display	"caption"	caption, hover, or hidden — how image descriptions are shown.
qdocPreview.showUnsupported	true	Show placeholders for constructs the preview cannot resolve.
qdocPreview.showTopicHeaders	true	Synthesize a page header from \class, \fn, …
qdocPreview.includeInternal	true	Render \internal blocks. QDoc hides them without --showinternal.
qdocPreview.scrollSync	true	Preview follows the cursor.
qdocPreview.updateDelay	300	Milliseconds of idle before re-rendering.
qdocPreview.excludeGlobs	node_modules, .git, build*, _build*	Skipped when scanning for .qdocconf.
qdocPreview.maxConfigFiles	4000	Cap on .qdocconf files collected per scan.

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:

Mode	Effect
caption	A visible line under the image. Default, so a missing description is obvious while writing.
hover	A tooltip only.
hidden	Nothing visible.

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.

Command	Purpose
Open Preview to the Side	Beside the editor. Bound to Cmd+K V / Ctrl+K V
Open Preview	In the current column
Refresh Preview	Re-read configuration and re-render
Rescan .qdocconf Files	Rebuild the cached index
Show Configuration Used for This File	Which .qdocconf was chosen, and what it provided
Lint All QDoc Comments in Folder	Fill the Problems panel for a whole checkout

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.