QDoc Linking Guidelines: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Provided info for controlling autolinking feature + minor fixes)
(Added links to relevant pages of QDoc manual.)
 
(2 intermediate revisions by the same user not shown)
Line 2: Line 2:
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]]
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]]


This page contains information about creating links to API pages and other articles and content.
QDoc allows linking to C++ API, QML API, other QDoc projects, and external sites. The QDoc Manual has a linking guide.


== Enabling Linking to Content Outside a Module ==
* [https://doc.qt.io/qt-6/qdoc-index.html QDoc Manual]
* [https://doc.qt.io/qt-6/08-qdoc-commands-creatinglinks.html Creating Links]


To link to a section, API, or page outside of the documentation project (content not included in the .qdocconf file), the module name must be set to the '''depends''' qdocconf variable.
== Linking to QDoc projects or Qt modules ==
 
To link to other QDoc projects, set the directory name to the '''depends''' variable of your project's .qdocconf file.
 
For example, to link to Qt Core, Qt QML, Qt GUI, and Qt Linguist pages such as API and examples, set the depends variable with the directory name:
<code>depends += qtcore qtqml qtgui qtlinguist </code>
<code>depends += qtcore qtqml qtgui qtlinguist </code>


The depends entry corresponds to the directories found in the '''QT_INSTALL_DOCS''' directory.
The depends entry corresponds to the directories found in the '''QT_INSTALL_DOCS''' directory.


'''Note''': To link to pages outside of the module, consider using the '''[]''' syntax as explained in the ''Resolving Ambiguous or Colliding Link Names'' section below.
For more information about linking to Qt documentation, visit the following pages from the QDoc Manual:
 
== Using QDoc's Autolink Feature ==
 
QDoc detects certain keywords such as class names, and attempts to create links to them. But if you have a typo (or the target API is renamed or removed), the link will not work without further warnings. It is therefore ''not'' anymore recommended in Qt documentation. '''Prefer adding links with the explicit \l command instead.'''
 
To prevent QDoc from creating a link for a keyword that would otherwise qualify for auto-linking, prefix the keyword with a backslash '''<nowiki/>'\'.''' To prevent auto-linking for all occurrences of a specific word, add it to the '''[https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#ignorewords ignorewords]''' configuration variable.
 
== Using the \l Command ==
In general, to create a link, use the [https://doc.qt.io/qt-6/08-qdoc-commands-creatinglinks.html#l-link \l command] followed by the link name.
<code>
\l{Link Name}
</code>
Valid link names include:
* Page title
* Page file name (.html)
* Class name
* QML Type name
* Targets created by '''[https://doc.qt.io/qt-6/08-qdoc-commands-creatinglinks.html#target \target]''' and '''[https://doc.qt.io/qt-6/08-qdoc-commands-creatinglinks.html#keyword \keyword]'''
* http://, https://, ftp://, mailto: URLs
* Section titles with the '''PageTitle#SectionTitle''' syntax
* API members such as properties and functions with the '''TypeName::member''' syntax. For example '''Button::checked'''
 
'''Notes:'''
 
* The parentheses '''()''' after QML or C++ functions are required. Do not add parentheses when linking to properties.
For example:
<code>
\l{Button::checked} - creates a link to the Button's checked property
\l{Button::clicked()} - creates a link to the Button's clicked() signal
</code>
* Typing '''\l{Button::}{clicked()}''' is a convenient shortcut for displaying a link to Button::clicked() as ''clicked()''.
 
* The space after the '''\l''' is not necessary if it is followed with '''{}''' as it adds unnecessary whitespace. Instead of '''\l {Page}''', type either '''\l{Page}''' or when there is only one word, '''\l Page'''.
 
=== Visible Text ===
 
Sometimes, to integrate the link name into the sentence or clause, the visible text is necessary.
 
* The '''\l{Signals & Slots#Advanced Signals and Slots Usage}{advanced signals and slots example}''' demonstrates a use for QSignalMapper.
 
== Resolving Ambiguous or Colliding Link Names ==
 
To disambiguate links, QDoc allows the author to specify the QDoc project and the type of API using
'''[]''' after the link command.
 
For example:
* '''\l[QML]{EnginioClient}''' - creates a link to the EnginioClient QML type
* '''\l[CPP]{EnginioClient}''' - creates a link to the EnginioClient C++ class
* '''\l[QtCore]{Qt}''' - creates a link to the Qt namespace
* '''\l[QtQml]{Qt}''' - creates a link to the Qt QML type
 
Currently only these parameters within '''[]''' are recognized:
* '''QML''' - for QML types, enumerations, or other definitions in QML modules (specified with )
* '''CPP''' - for C++ APIs
* project or module name
 
'''Note:''' The project name is specified in the QDoc configuration file ('''.qdocconf''').
 
== External Pages ==
To avoid multiple instances of ''hard-coded'' HTTP URLs, use the '''\externalpage''' command to associate the HTTP URL
with a title.
<code>
\externalpage https://www.example.com
\title An Example Page
</code>
 
'''\l{An Example Page}''' creates link to http://www.example.com. There is a set of external pages in ''qtbase/doc/global/externalsites''
directory. The command can be declared in the module documentation directory if it is not used anywhere else in Qt to avoid being unnecessarily included in other modules' index files.
 
== Various Guidelines ==


* It is best if the link title and visible text are in the same line so that they are more readable and easily searched.
* [https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#depends depends variable]
* Be mindful about colliding titles by avoiding certain keywords or by creating descriptive page titles.
* [https://doc.qt.io/qt-6/qdoc-guide-conf.html Creating QDoc Configuration Files]
* Linking directly to the HTML filename should be used as a last resort because the filename can change.
* [https://doc.qt.io/qt-6/25-qdoc-configuration-derivedprojects.html#description Supporting Derived Projects]

Latest revision as of 14:39, 14 October 2024

This page is part of the Qt Writing Guidelines

QDoc allows linking to C++ API, QML API, other QDoc projects, and external sites. The QDoc Manual has a linking guide.

Linking to QDoc projects or Qt modules

To link to other QDoc projects, set the directory name to the depends variable of your project's .qdocconf file.

For example, to link to Qt Core, Qt QML, Qt GUI, and Qt Linguist pages such as API and examples, set the depends variable with the directory name: 

depends += qtcore qtqml qtgui qtlinguist

The depends entry corresponds to the directories found in the QT_INSTALL_DOCS directory.

For more information about linking to Qt documentation, visit the following pages from the QDoc Manual:

Retrieved from "https://wiki.qt.io/index.php?title=QDoc_Linking_Guidelines&oldid=42994"