qdoc: Add support for generating links to source code in C++ referenceHEADdev

Define a set of new configuration variables, `url.examples` and its
sub-variables, that allow for automatic linking to a service for
browsing the projects source code, such as code.qt.io.

Restrict the feature to C++ API as QDoc receives accurate location
information for C++ entities from Clang. Majority of QML APIs in
Qt are implemented in C++; often the only direct connection between
QML declarations and the source code (that is visible to QDoc) is the
source of the documentation comment itself, making this feature less
reliable for QML.

In order to generate a valid URL that includes the path relative to
the project (repository) root directory, add a `url.sources.rootdir`
variable that is explicitly interpreted as a path in the file system
and validated. Allow injecting the path and line number components
into the URL at select locations, using \1 and \2 as placeholders,
respectively.

Add `url.sources.linktext` to control the user-visible link text
for the generated source links.

Add `url.sources.enabled` for explicitly enabling the new feature.
In a multi-module documentation project such as Qt, each module
can maintain a source URL configuration, and it can be selectively
enabled for specific types of builds (online vs. offline
documentation) in the global configuration.

[ChangeLog][QDoc] QDoc can now automatically generate links to the
source code in C++ reference pages.

Fixes: QTBUG-134268
Change-Id: I5bec0925e5cf2be48e0dc65bf9cbe3609b22c77a
Reviewed-by: Topi Reiniö <[email protected]>

0 files changed, 0 insertions, 0 deletions