Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qdoc-manual-qdocconf.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2021 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\page 21-0-qdoc-configuration.html
6
\previouspage Miscellaneous Macros
7
\nextpage Generic Configuration Variables
8
9
\title The QDoc Configuration File
10
11
Before running QDoc, you must create a QDoc configuration file to
12
tell QDoc where to find the source files that contain the QDoc
13
comments. The pathname to your configuration file is passed to
14
QDoc on the command line:
15
16
\quotation
17
\c {/current/dir$ ../../bin/qdoc ./config.qdocconf}
18
\endquotation
19
20
\section1 General Description
21
22
The configuration file is a list of entries of the form \e
23
{"variable = value"}. Using the configuration variables, you can
24
define where QDoc should find the various source files, images and
25
examples, where to put generated documentation etc. The
26
configuration file can also contain directives like \c
27
include. For an example, see \l minimum.qdocconf.
28
29
You can also use configuration variables to get QDoc to support
30
\l{Supporting Derived Projects} {derived projects}, i.e QDoc can
31
generate links in your project's documentation to elements in the
32
Qt online documentation. See the \l {Supporting Derived projects}
33
section.
34
35
A valid configuration variable name can include upper and lower case
36
letters, numbers, and an underscore, '_'.
37
38
The value of a configuration variable can be set using either '='
39
or '+='. The difference is that '=' overrides the previous value,
40
while '+=' adds a new value to the current one.
41
42
Values of some configuration variables are interpreted as a list of
43
strings, for example:
44
\l {sourcedirs-variable}
45
{\c{sourcedirs}}, while others are treated as a single string. Double
46
quotes around a value string are optional, but including them allows
47
you to use special characters like '=' and ' \" ' within the value
48
string, for example:
49
50
\badcode
51
HTML.postheader = "<a href=\"index.html\">Home</a>"
52
\endcode
53
54
If an entry spans many lines, use a backslash at the end of every
55
line but the last:
56
57
\badcode
58
sourcedirs = kernel tools widgets
59
\endcode
60
61
This can be written as:
62
\badcode
63
sourcedirs = kernel \
64
tools \
65
widgets
66
\endcode
67
68
If a value spans multiple lines but is interpreted as a single string,
69
the lines are joined with spaces.
70
71
\section1 Expansion of Configuration Values
72
73
QDoc supports expanding environment variables within configuration files.
74
For example, Qt modules rely on the environment variable QT_INSTALL_DOCS
75
to include definitions related to all Qt module documentation projects:
76
77
\badcode
78
include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
79
\endcode
80
81
A variable to expand is prefixed with '$'. To use the literal character
82
'$' within a value string, escape it with a backslash: '\\$'.
83
84
Since QDoc 6.0, values can be expanded also from other configuration
85
variables. In addition to the \c {$variable} syntax, also \c {${variable}}
86
is valid. The latter eliminates the need to separate the variable
87
name with whitespace or non-variable characters. For example:
88
89
\badcode
90
baseurl = https://doc.qt.io/
91
...
92
url = ${baseurl}qtcreator
93
\endcode
94
95
If the target variable refers to a list of strings, they will be
96
joined using spaces in the expanded value:
97
98
\badcode
99
vars = foo \
100
bar \
101
baz
102
103
items = "Items: $vars" # Expands to "Items: foo bar baz"
104
\endcode
105
106
Controlling which character is used for joining the string list is also
107
possible:
108
109
\badcode
110
items = "Items: ${vars,|}" # Expands to "Items: foo|bar|baz"
111
items = "Items: ${vars,,}" # Expands to "Items: foo,bar,baz"
112
items = "Items: ${vars,}" # Expands to "Items: foobarbaz"
113
\endcode
114
115
As the expansion is performed after reading in all variables, the order
116
in which they are defined does not matter.
117
118
\note Nested variable expansion is not supported.
119
120
\section2 Expanding Environment Variables
121
122
When expanding environment variables, the \c {${variable}} syntax has
123
different behavior compared to \c {$variable}. The former expands the
124
content of the variable in place to be parsed as part of the
125
configuration file, while the latter simply assigns the content as a
126
value for the current configuration variable. This has implications if
127
the environment variable contains a list of elements separated by
128
whitespace, or other formatting recognized by QDoc.
129
130
For example, if the value of an environment variable \c SRCDIRS is
131
\c {"../src/a ../src/b"}, then
132
133
\badcode
134
sourcedirs = $SRCDIRS # Fail - value is interpreted as a single path.
135
sourcedirs = ${SRCDIRS} # Ok - whitespace is used as a delimiter.
136
\endcode
137
138
\section1 Configuration Variables
139
140
\section2 Variable List
141
142
\list
143
\li \l {defines-variable} {defines}
144
\li \l {depends-variable} {depends}
145
\li \l {exampledirs-variable} {exampledirs}
146
\li \l {examples-variable} {examples}
147
\li \l {examplesinstallpath-variable} {examplesinstallpath}
148
\li \l {examples.fileextensions-variable} {examples.fileextensions}
149
\li \l {examples.warnaboutmissingimages-variable} {examples.warnaboutmissingimages}
150
\li \l {examples.warnaboutmissingprojectfiles-variable} {examples.warnaboutmissingprojectfiles}
151
\li \l {excludedirs-variable} {excludedirs}
152
\li \l {excludefiles-variable} {excludefiles}
153
\li \l {extraimages-variable} {extraimages}
154
\li \l {falsehoods-variable} {falsehoods}
155
\li \l {headerdirs-variable} {headerdirs}
156
\li \l {headers-variable} {headers}
157
\li \l {headers.fileextensions-variable} {headers.fileextensions}
158
\li \l {HTML.footer-variable} {HTML.footer}
159
\li \l {HTML.postheader-variable} {HTML.postheader}
160
\li \l {HTML.style-variable} {HTML.style}
161
\li \l {includepaths-variable} {includepaths}
162
\li \l {ignorewords-variable} {ignorewords}
163
\li \l {ignoresince-variable} {ignoresince}
164
\li \l {imagedirs-variable} {imagedirs}
165
\li \l {indexes-variable} {indexes}
166
\li \l {language-variable} {language}
167
\li \l {locationinfo-variable} {locationinfo}
168
\li \l {macro-variable} {macro}
169
\li \l {manifestmeta-variable} {manifestmeta}
170
\li \l {moduleheader-variable} {moduleheader}
171
\li \l {navigation-variable} {navigation}
172
\li \l {outputdir-variable} {outputdir}
173
\li \l {outputformats-variable} {outputformats}
174
\li \l {outputprefixes-variable} {outputprefixes}
175
\li \l {outputsuffixes-variable} {outputsuffixes}
176
\li \l {productname-variable} {productname}
177
\li \l {project-variable} {project}
178
\li \l {sourcedirs-variable} {sourcedirs}
179
\li \l {sources-variable} {sources}
180
\li \l {sources.fileextensions-variable} {sources.fileextensions}
181
\li \l {spurious-variable} {spurious}
182
\li \l {tabsize-variable} {tabsize}
183
\li \l {url-variable} {url}
184
\li \l {url.examples-variable} {url.examples}
185
\li \l {version-variable} {version}
186
\li \l {versionsym-variable} {versionsym}
187
\li \l {warninglimit-variable} {warninglimit}
188
\endlist
189
190
\section2 Categories
191
192
\list
193
\li \l {Generic Configuration Variables}
194
\li \l {Format-specific Configuration Variables}
195
\endlist
196
197
\section1 Configuration File Examples
198
199
\list
200
\li A minimum configuration file: \l minimum.qdocconf
201
\li The Qt configuration file: \l qtgui.qdocconf
202
\endlist
203
*/
204
205
206
/*!
207
\page 22-qdoc-configuration-generalvariables.html
208
\previouspage The QDoc Configuration File
209
\nextpage Creating Help Project Files
210
211
\title Generic Configuration Variables
212
213
With the general QDoc configuration variables, you can define
214
where QDoc will find the various source files it needs to generate
215
the documentation, as well as the directory to put the generated
216
documentation. You can also do some minor manipulation of QDoc
217
itself, controlling its output and processing behavior.
218
219
\target codeindent-variable
220
\section1 codeindent
221
222
The \c codeindent variable specifies the level of indentation that
223
QDoc uses when writing code snippets.
224
225
QDoc originally used a hard-coded value of four spaces for code
226
indentation to ensure that code snippets could be easily
227
distinguished from surrounding text. Since we can use \l{HTML
228
Specific Configuration Variables#HTML.stylesheets} {stylesheets}
229
to adjust the appearance of certain types of HTML elements, this
230
level of indentation is not always required.
231
232
\target codeprefix-variable
233
\target codesuffix-variable
234
\section1 codeprefix, codesuffix
235
236
The \c codeprefix and \c codesuffix variables specify a pair of
237
strings that each code snippet is enclosed in.
238
239
\target defines-variable
240
\section1 defines
241
242
The \c defines variable specifies the C++ preprocessor symbols
243
that QDoc will recognize and respond to.
244
245
When a preprocessor symbol is specified using the \c defines
246
variable, you can also use the \l {if-command} {\\if} command to
247
enclose documentation that only will be included if the
248
preprocessor symbol is defined.
249
250
\badcode
251
defines = QT_GUI_LIB
252
\endcode
253
254
This ensures that QDoc will process the code that requires these
255
symbols to be defined. For example:
256
257
\code
258
#ifdef Q_GUI_LIB
259
void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1)
260
#endif
261
\endcode
262
263
264
You can also define preprocessor symbols manually on the command
265
line using the -D option. For example:
266
267
\badcode
268
currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf
269
\endcode
270
271
In this case the -D option ensures that the \c qtforpython
272
preprocessor symbol is defined when QDoc processes the source
273
files defined in the qtgui.qdocconf file.
274
275
See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}.
276
277
\target depends-variable
278
\section1 depends
279
280
The \c depends variable defines a list of other documentation projects
281
that this project depends on for resolving link targets for type
282
inheritance and anything else the documentation needs to link to.
283
284
Like Qt itself, documentation for Qt is distributed across multiple
285
modules. In a multi-module documentation project, the minimum set
286
of dependencies for a single module consists of actual build
287
dependencies. In addition, if there is a documentation project
288
(module) that acts as a top-level entry point for the entire
289
documentation set and provides \l {navigation-variable}{navigation}
290
links, each module documentation should include it as a dependency.
291
292
When QDoc generates documentation for a project, it will also generate
293
an \c .index file containing URLs to each linkable entity in the project.
294
Each dependency is a (lowercase) name of a project. This name must
295
match with the base name of the index file generated for that
296
project.
297
298
\badcode
299
depends = \
300
qtdoc \
301
qtcore \
302
qtquick
303
\endcode
304
305
When invoking QDoc on a project that has dependencies and uses the
306
\c depends variable, one or more \c -indexdir path(s) must be passed
307
as command line option(s). QDoc uses these paths to search for
308
the dependencies' index files.
309
310
\badcode
311
qdoc mydoc.qdocconf -outputdir $PWD/html -indexdir $QT_INSTALL_DOCS
312
\endcode
313
314
With above, QDoc will search for a file
315
\c {$QT_INSTALL_DOCS/qtdoc/qtdoc.index} for a dependency to \c qtdoc.
316
If an index file for a dependency is not found, QDoc will output a
317
warning.
318
319
The \c depends command accepts also a special value of '*'. This
320
instructs QDoc to load all index files found in specified index
321
directories; that is, "depends on everything".
322
323
\badcode
324
depends = *
325
\endcode
326
327
See also \l indexes, \l project, and \l url.
328
329
\target exampledirs-variable
330
\section1 exampledirs
331
332
The \c exampledirs variable specifies the directories containing
333
the source code of the example files.
334
335
The \l {examples-variable} {examples} and \l
336
{exampledirs-variable} {exampledirs} variables are used by the \l
337
{quotefromfile-command} {\\quotefromfile}, \l {quotefile-command}
338
{\\quotefile} and \l {example-command} {\\example} commands. If
339
both the \l {examples-variable} {examples} and \l
340
{exampledirs-variable} {exampledirs} variables are defined, QDoc
341
will search in both, first in \l {examples-variable} {examples}
342
then in \l {exampledirs-variable} {exampledirs}.
343
344
QDoc will search through the directories in the specified order,
345
and accept the first matching file it finds. It will only search
346
in the specified directories, \e not in subdirectories.
347
348
\badcode
349
exampledirs = $QTDIR/doc/src \
350
$QTDIR/examples \
351
$QTDIR \
352
$QTDIR/qmake/examples
353
354
examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
355
\endcode
356
357
When processing
358
359
\badcode
360
\quotefromfile widgets/calculator/calculator.cpp
361
\endcode
362
363
QDoc will see if there is a file called \c calculator.cpp
364
listed as a value in the \l {examples-variable} {\c examples} variable. If
365
there isn't, it will search in the \c exampledirs variable, and
366
first see if there exists a file called
367
368
\badcode
369
$QTDIR/doc/src/widgets/calculator/calculator.cpp
370
\endcode
371
372
If it doesn't, QDoc will continue looking for a file called
373
374
\badcode
375
$QTDIR/examples/widgets/calculator/calculator.cpp
376
\endcode
377
378
and so forth.
379
380
See also \l {examples-variable}{examples}.
381
382
\target examples-variable
383
\section1 examples
384
385
The \c examples variable allows you to specify individual example
386
files in addition to those located in the directories specified by
387
the \l {exampledirs-variable} {\c exampledirs} variable.
388
389
The \c examples and \l {exampledirs-variable} {\c exampledirs}
390
variables are used by the \l {quotefromfile-command}
391
{\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l
392
{example-command} {\\example} commands. If both the \c examples and \l
393
{exampledirs-variable} {\c exampledirs} variables are defined,
394
QDoc will search in both, first in \c examples then in \l
395
{exampledirs-variable} {\c exampledirs}.
396
397
QDoc will search through the values listed for the \c examples
398
variable, in the specified order, and accept the first one it
399
finds.
400
401
For an extensive example, see the \l {exampledirs-variable} {\c
402
exampledirs} command. But note that if you know the file is listed
403
in the \c examples variable, you don't need to specify its path:
404
405
\badcode
406
\quotefromfile calculator.cpp
407
\endcode
408
409
See also \l {exampledirs-variable} {exampledirs}.
410
411
\target examplesinstallpath-variable
412
\section1 examplesinstallpath
413
414
The \c examplesinstallpath variable sets the root path for this
415
project's examples under the \e installed example directory.
416
417
Assuming a root install path of \c QT_INSTALL_EXAMPLES for all
418
examples, then the path
419
420
\badcode
421
<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>
422
\endcode
423
424
will be used to refer to a path of a single example within this
425
documentation project. These paths are recorded in the
426
\l {Example Manifest Files} {example manifest file}, read by Qt
427
Creator.
428
429
To ensure correct paths, \c examplesinstallpath must match with
430
one of the directories listed in \l {exampledirs-variable}
431
{exampledirs}. The path passed as an argument for each
432
\l {example-command} {\\example} command is relative to
433
the path in \e exampledirs.
434
435
For example:
436
437
\badcode
438
exampledirs = ./snippets \
439
../../../examples/mymodule
440
441
examplesinstallpath = mymodule
442
\endcode
443
444
And given a following \\example command:
445
446
\badcode *
447
/*!
448
\example basic/hello
449
...
450
\1/
451
\endcode
452
453
Then, the path \c {mymodule/basic/hello} is recorded in the manifest file
454
for this example.
455
456
\note It is possible to override \c examplesinstallpath for an individual
457
\l {example-command}{\\example} using the \l {meta-command}{\\meta}
458
command.
459
460
\b {See also}: \l {exampledirs}, \l {example-command} {\\example}, and
461
\l {meta-command}{\\meta}.
462
463
\target examples.fileextensions-variable
464
\section1 examples.fileextensions
465
466
The \c examples.fileextensions variable specifies the file
467
extensions that QDoc will look for when collecting example files
468
for display in the documentation.
469
470
The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml
471
and *.ui.
472
473
The extensions are given as standard wildcard expressions. You
474
can add a file extension to the filter using '+='. For example:
475
476
\badcode
477
examples.fileextensions += *.qrc
478
\endcode
479
480
See also \l{headers.fileextensions}.
481
482
\target examples.warnaboutmissingimages-variable
483
\section1 examples.warnaboutmissingimages
484
485
While processing example documentation, QDoc may emit warnings if an example
486
doesn't contain any images. This warning can be disabled by setting the
487
following configuration variable in the .qdocconf file for the project:
488
489
\c {examples.warnaboutmissingimages = false}
490
491
This configuration variable was introduced to QDoc with Qt 6.9.
492
493
See also \l{examples.warnaboutmissingprojectfiles-variable}
494
{examples.warnaboutmissingprojectfiles}.
495
496
\target examples.warnaboutmissingprojectfiles-variable
497
\section1 examples.warnaboutmissingprojectfiles
498
499
While processing example documentation, QDoc may emit warnings if an example
500
doesn't contain a project file. This warning can be disabled by setting the
501
following configuration variable in the .qdocconf file for the project:
502
503
\c {examples.warnaboutmissingprojectfiles = false}
504
505
This configuration variable was introduced to QDoc with Qt 6.9.
506
507
See also \l{examples.warnaboutmissingimages-variable}
508
{examples.warnaboutmissingimages}.
509
510
\target excludedirs-variable
511
\section1 excludedirs
512
513
The \c excludedirs variable is for listing directories that should \e{not}
514
be processed by QDoc, even if the same directories are included by the
515
\l {sourcedirs-variable} {sourcedirs} or \l {headerdirs-variable} {headerdirs}
516
variables.
517
518
For example:
519
520
\badcode
521
sourcedirs = src/corelib
522
excludedirs = src/corelib/tmp
523
\endcode
524
525
When executed, QDoc will exclude the listed directories from
526
further consideration. Files in these directories will not be
527
read by QDoc.
528
529
See also \l {excludefiles-variable} {excludefiles}.
530
531
\target excludefiles-variable
532
\section1 excludefiles
533
534
The \c excludefiles variable allows you to specify individual files
535
that should \e{not} be processed by QDoc.
536
537
\badcode
538
excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
539
$QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp
540
\endcode
541
542
If you include the above in your qdocconf file for qtbase, there
543
will be no class documentation generated for QWidget.
544
545
Since Qt 5.6, also simple wildcards ('*' and '?') are recognized by
546
\c excludefiles. For example, to exclude all private Qt header files
547
from being parsed, define the following:
548
549
\badcode
550
excludefiles += "*_p.h"
551
\endcode
552
553
See also \l {excludedirs-variable} {excludedirs}.
554
555
\target extraimages-variable
556
\section1 extraimages
557
558
The \c extraimages variable tells QDoc to incorporate specific
559
images in the generated documentation.
560
561
QDoc automatically copies an image file from \l imagedirs to the output
562
directory if it's referenced by the \l {image-command} {\c{\image}} or
563
\l {inlineimage-command} {\c{\inlineimage}} command. If you want to copy
564
additional images, you must specify them using the \c extraimages variable.
565
566
The general syntax is \tt {\e{format}.extraimages = \e image}.
567
568
For a contextualized example, refer to the description of the
569
\l {HTML.postheader-variable}{HTML.postheader} variable.
570
571
Example:
572
\badcode
573
HTML.extraimages = images/qt-logo.png
574
\endcode
575
576
See also \l images and \l imagedirs.
577
578
\target falsehoods-variable
579
\section1 falsehoods
580
581
The \c falsehoods variable defines the truth value of specified
582
preprocessor symbols as false.
583
584
The values of the variable are regular expressions (see QRegularExpression
585
for details). If this variable is not set for a preprocessor
586
symbol, QDoc assumes its truth value is true. The exception is
587
'0', which is always false.
588
589
QDoc will recognize, and is able to evaluate, the following
590
preprocessor syntax:
591
592
\code
593
#ifdef NOTYET
594
...
595
#endif
596
597
#if defined (NOTYET)
598
...
599
#end if
600
\endcode
601
602
However, faced with unknown syntax like
603
604
\code
605
#if NOTYET
606
...
607
#endif
608
\endcode
609
610
QDoc will evaluate it as true by default, \e unless the
611
preprocessor symbol is specified within the \c falsehoods variable
612
entry:
613
614
\badcode
615
falsehoods = NOTYET
616
\endcode
617
618
See also \l defines.
619
620
\target generateindex-variable
621
\section1 generateindex
622
623
The \c generateindex variable contains a boolean value that
624
specifies whether to generate an index file when HTML
625
documentation is generated.
626
627
By default, an index file is always generated with HTML
628
documentation, so this variable is typically only used when
629
disabling this feature (by setting the value to \c false) or when
630
enabling index generation for the WebXML output (by setting the
631
value to \c true).
632
633
\target headerdirs-variable
634
\section1 headerdirs
635
636
The \c headerdirs variable specifies the directories containing
637
the header files associated with the \c .cpp source files used in
638
the documentation.
639
640
\badcode
641
headerdirs = $QTDIR/src \
642
$QTDIR/extensions/activeqt \
643
$QTDIR/extensions/motif \
644
$QTDIR/tools/designer/src/lib/extension \
645
$QTDIR/tools/designer/src/lib/sdk \
646
$QTDIR/tools/designer/src/lib/uilib
647
\endcode
648
649
When executed, the first thing QDoc will do is to read through the
650
headers specified in the \l {headers} {\c headers} variable, and
651
the ones located in the directories specified in the \c headerdir
652
variable (including all subdirectories), building an internal
653
structure of the classes and their functions.
654
655
Then it will read through the sources specified in the \l
656
{sources-variable} {\c sources}, and the ones located in the
657
directories specified in the \l {sourcedirs-variable} {\c
658
sourcedirs} varible (including all subdirectories), merging the
659
documentation with the structure it retrieved from the header
660
files.
661
662
If both the \c headers and \c headerdirs variables are defined,
663
QDoc will read through both, first \l {headers} {\c headers} then
664
\c headerdirs.
665
666
In the specified directories, QDoc will only read the files with
667
the \c fileextensions specified in the \l {headers.fileextensions}
668
{\c headers.fileextensions} variable. The files specified by
669
\l {headers} {\c headers} will be read without taking into account
670
their fileextensions.
671
672
See also \l headers and \l headers.fileextensions.
673
674
\target headers-variable
675
\section1 headers
676
677
The \c headers variable allows you to specify individual header
678
files in addition to those located in the directories specified by
679
the \l {headerdirs} {\c headerdirs} variable.
680
681
\badcode
682
headers = $QTDIR/src/gui/widgets/qlineedit.h \
683
$QTDIR/src/gui/widgets/qpushbutton.h
684
\endcode
685
686
When processing the \c headers variable, QDoc behaves in the same
687
way as it does when processing the \l {headerdirs} {\c headerdirs}
688
variable. For more information, see the \l {headerdirs} {\c
689
headerdirs} variable.
690
691
See also \l headerdirs.
692
693
\target headers.fileextensions-variable
694
\section1 headers.fileextensions
695
696
The \c headers.fileextensions variable specify the extension used
697
by the headers.
698
699
When processing the header files specified in the \l {headerdirs}
700
{\c headerdirs} variable, QDoc will only read the files with the
701
fileextensions specified in the \c headers.fileextensions
702
variable. In this way QDoc avoids spending time reading irrelevant
703
files.
704
705
The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp, and
706
*.hxx.
707
708
The extensions are given as standard wildcard expressions. You
709
can add a file extension to the filter using '+='. For example:
710
711
\badcode
712
header.fileextensions += *.H
713
\endcode
714
715
\warning The above assignment may not work as described.
716
717
See also \l headerdirs.
718
719
\target includepaths-variable
720
\section1 includepaths
721
722
The \c includepaths variable is used for passing additional
723
include paths to the Clang parser that QDoc uses for parsing C++
724
code for documentation comments.
725
726
The variable accepts a list of paths, prefixed with \c{-I} (include
727
path), \c {-F} (\macos framework include path), or \c{-isystem}
728
(system include path). If a prefix is omitted, \c{-I} is used by
729
default.
730
731
Paths relative to the current .qdocconf file are resolved into
732
absolute paths. Paths that do not exist in the file system are
733
ignored.
734
735
\note For Qt documentation projects, the build system typically
736
provides the required include paths as command line
737
arguments when invoking QDoc.
738
739
See also \l moduleheader.
740
741
\target ignorewords-variable
742
\section1 ignorewords
743
744
The \c ignorewords variable is used for specifying a list of strings
745
that QDoc will ignore when resolving hyperlink targets.
746
747
QDoc has an auto-linking feature, where linking is attempted for words
748
that resemble C++ or QML entities. Specifically, a string
749
qualifies for auto-linking if it is at least three characters in
750
length, has no whitespace, and it
751
752
\list
753
\li is a \e camelCase word, that is, it contains at least one
754
uppercase character at index greater than zero, or
755
\li contains the substring \c {()} or \c {::}, or
756
\li contains at least one special character, \c {@} or \c {_}.
757
\endlist
758
759
Adding a qualified word to \c ignorewords stops QDoc from linking
760
that word automatically. For example, if the word \e OpenGL is a
761
valid link target (a section, \l{page-command}{\\page}, or
762
\l {externalpage-command}{\\externalpage} title), a hyperlink for
763
each occurrence can be avoided with
764
765
\badcode
766
ignorewords += OpenGL
767
\endcode
768
769
Linking explicitly with \l {l-command}{\\l} continues to work for
770
ignored words.
771
772
The \c ignorewords variable was introduced in QDoc 5.14.
773
774
\target ignoresince-variable
775
\section1 ignoresince
776
777
The \c ignoresince variable is used for setting a cutoff value for
778
versions passed to the \l {since-command}{\\since} command. All
779
\\since commands that define a version lower than the cutoff are
780
ignored and do not generate output.
781
782
The cutoff values are project-specific. The project name can be
783
defined as a subvariable. The default project name is \e Qt. For
784
example:
785
786
\badcode
787
ignoresince = 5.0
788
ignoresince.QDoc = 5.0
789
\endcode
790
791
These will ignore \\since commands where the major version is 4
792
or lower and the project is either \c QDoc or undefined.
793
794
\badcode
795
\since 3.2 # Ignored
796
\since 5.2 # Documented (as 'Qt 5.2')
797
\since QDoc 4.6 # Ignored
798
\since QtQuick 2.5 # Documented
799
\endcode
800
801
The \c ignoresince variable was introduced in QDoc 5.15.
802
803
See also \l {since-command}{\\since}.
804
805
\target imagedirs-variable
806
\section1 imagedirs
807
808
The \c imagedirs variable specifies the directories containing the
809
images used in the documentation.
810
811
The \l {images} {\c images} and \c imagedirs variables are used by
812
the \l {image-command} {\\image} and \l {inlineimage-command}
813
{\\inlineimage} commands. If both the \l {images} {\c images} and
814
\c imagedirs variables are defined, QDoc will search in both. First
815
in \l {images} {\c images}, then in \c imagedirs.
816
817
QDoc will search through the directories in the specified order,
818
and accept the first matching file it finds. It will only search
819
in the specified directories, \e not in subdirectories.
820
821
\badcode
822
imagedirs = $QTDIR/doc/src/images \
823
$QTDIR/examples
824
825
images = $QTDIR/doc/src/images/calculator-example.png
826
\endcode
827
828
When processing
829
830
\badcode
831
\image calculator-example.png
832
\endcode
833
834
QDoc will then see if there is a file called
835
calculator-example.png listed as a value in the \c images
836
variable. If there isn't, it will search in the \c imagedirs
837
variable for:
838
839
\badcode
840
$QTDIR/doc/src/images/calculator-example.png
841
\endcode
842
843
If the file doesn't exist, QDoc will look for a file called
844
845
\badcode
846
$QTDIR/examples/calculator-example.png
847
\endcode
848
849
\target language-variable
850
\section1 language
851
852
The \c language variable specifies the language of the source code
853
that is used in the documentation. Specifically, it defines the
854
default language for parsing source code within \\code .. \\endcode
855
blocks.
856
857
\badcode
858
language = Cpp
859
\endcode
860
861
The default language is C++ (Cpp), and doesn't need to be explicitly
862
specified. If the code snippets in the documentation consist mainly
863
of QML code, set QML as the default:
864
865
\badcode
866
language = QML
867
\endcode
868
869
See also \l {code-command}[\\code}.
870
871
\target locationinfo-variable
872
\section1 locationinfo
873
874
The \c locationinfo boolean variable determines whether detailed
875
location information about each entity is written to
876
\c {.index}-files and \c {.webxml}-files (when using the WebXML
877
output format).
878
879
Location information consists of the full path and line
880
number of either the declaration or documentation comment block
881
in the source code.
882
883
Setting this to \c false turns off location info:
884
885
\badcode
886
locationinfo = false
887
\endcode
888
889
The default value is \c true.
890
891
The \c locationinfo variable was introduced in QDoc 5.15.
892
893
\target macro-variable
894
\section1 macro
895
896
The \c macro variable is used to create your own simple QDoc
897
commands. The syntax is \tt {macro.\e{command} = \e{definition}},
898
where the definition is written using QDoc syntax.
899
900
A macro variable can be restricted for use in one type of output
901
generation. By appending \c {.HTML} to the macro name, for
902
example, the macro is only used when generating HTML output.
903
904
\badcode
905
macro.key = "\\b"
906
macro.raisedaster.HTML = "<sup>*</sup>"
907
\endcode
908
909
The first macro defines the \\key command to render its argument
910
using a bold font. The second macro defines the \\raisedaster
911
command to render a superscript asterisk, but only when generating
912
HTML.
913
914
A macro can also take up to seven parameters:
915
916
\badcode
917
macro.hello = "Hello \1!"
918
\endcode
919
920
Parameters are passed to macros the same way as to other commands:
921
922
\badcode
923
\hello World
924
\endcode
925
926
When using more than one parameter, or when an argument
927
contains whitespace, enclose each argument in braces:
928
929
\badcode
930
macro.verinfo = "\1 (version \2)"
931
\endcode
932
933
\badcode
934
\verinfo {QFooBar} {1.0 beta}
935
\endcode
936
937
A special macro option, \e match, can be added for additional
938
regular expression pattern matching for expanded macros.
939
940
For example,
941
942
\badcode
943
macro.qtminorversion = "$QT_VER"
944
macro.qtminorversion.match = "\\d+\\.(\\d+)"
945
\endcode
946
947
This creates a macro \\qtminorversion that expands to the minor
948
version based on the QT_VER environment variable.
949
950
A macro that defines a match pattern outputs all capture groups
951
(parentheses) concatenated together, or the exact matched string
952
if the pattern does not contain any capture groups.
953
954
For more information about pre-defined macros, see \l {Macros}.
955
956
\target manifestmeta-variable
957
\section1 manifestmeta
958
959
The \c manifestmeta variable specifies additional meta-content
960
for the example manifest files generated by QDoc.
961
962
See the \l{Manifest Meta Content} section for more information.
963
964
\target moduleheader-variable
965
\section1 moduleheader
966
967
The \c moduleheader variable defines the name of the module
968
header of a documented C++ module.
969
970
Projects that document C++ APIs require a module-level header
971
that includes all public classes, namespaces and header files
972
for the module. The Clang parser in QDoc uses this file to
973
build a pre-compiled header (PCH) for the module to increase
974
the speed of parsing source files.
975
976
By default, the \l{project-variable}{project} name is used
977
also as the module header name.
978
979
\badcode
980
project = QtCore
981
\endcode
982
983
With the above project name, QDoc searches a module header
984
\e QtCore in all known include paths; first using the paths
985
passed as command line arguments, then the paths listed in
986
the \l includepaths variable.
987
988
QDoc will issue a warning if the module header is not found.
989
It will then attempt to build an artificial module header
990
based on the headers listed in the \l {headerdirs-variable}
991
{headerdirs} variable.
992
993
For Qt documentation projects, the build system typically
994
provides QDoc with correct include paths to locate the
995
module header, provided that the \c project variable is set
996
correctly. The \c moduleheader variable provides an
997
alternative file name for QDoc to search for.
998
999
If the project contains no C++ documentation, QDoc should be
1000
instructed to skip generating a PCH by setting \c moduleheader
1001
to an empty string:
1002
1003
\badcode
1004
# No C++ code to document in this project
1005
moduleheader =
1006
\endcode
1007
1008
See also \l includepaths and \l project.
1009
1010
\target naturallanguage-variable
1011
\section1 naturallanguage
1012
1013
The \c naturallanguage variable specifies the natural language
1014
used for the documentation generated by QDoc.
1015
1016
\badcode
1017
naturallanguage = zh-Hans
1018
\endcode
1019
1020
By default, the natural language is \c en for compatibility with
1021
legacy documentation.
1022
1023
QDoc will add the natural language information to the HTML it
1024
generates, using the \c lang and \c xml:lang attributes.
1025
1026
See also \l {sourceencoding-variable} {sourceencoding},
1027
\l {outputencoding-variable} {outputencoding},
1028
\l{http://www.w3.org/TR/xhtml1/#C_7}
1029
{C.7. The lang and xml:lang Attributes} and
1030
\l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}
1031
{Best Practice 13: Using Hans and Hant codes}.
1032
1033
\target navigation-variable
1034
\section1 navigation
1035
1036
The \c navigation sub-variables, if defined, set the home page, landing
1037
page, C++ classes page, and QML types page that are visible in the
1038
generated navigation bar for each page.
1039
1040
In a project with multiple sub-projects (for example, Qt modules), each
1041
sub-project typically defines its own landing page while the same home
1042
page is used across all sub-projects.
1043
1044
\b Sub-variables
1045
1046
\table
1047
\row \li \c navigation.homepage
1048
\li Project home page.
1049
\row \li \c navigation.hometitle
1050
\li (Optional) User-visible title for the home page.
1051
Default value is taken from \c homepage.
1052
\row \li \c navigation.landingpage
1053
\li Sub-project landing page.
1054
\row \li \c navigation.landingtitle
1055
\li (Optional) User-visible title for the landing page.
1056
Defaults value is taken from \c landingpage.
1057
\row \li \c navigation.cppclassespage
1058
\li Top-level page that lists all C++ classes for this (sub-)project.
1059
Typically, the title of a \l {module-command}{\\module} page.
1060
\row \li \c navigation.cppclassestitle
1061
\li (Optional) User-visible title for the C++ classes page.
1062
Default is "C++ Classes".
1063
\row \li \c navigation.qmltypespage
1064
\li Top-level page that lists all QML types for this (sub-)project.
1065
Typically, the title of a \l {qmlmodule-command}{\\qmlmodule} page.
1066
\row \li \c navigation.qmltypestitle
1067
\li (Optional) User-visible title for the QML types page.
1068
Default is "QML Types".
1069
\row \li \c navigation.toctitles (Since QDoc 6.0)
1070
\li Page title(s) containing a \l {list-command}{\\list} structure that
1071
acts as a table of contents (TOC). QDoc generates navigation links
1072
for pages listed in the TOC, without the need for
1073
\l {nextpage-command}{\\nextpage} and \l {previouspage-command}
1074
{\\previouspage} commands, as well as a navigation hierarchy that's
1075
visible in the navigation bar (breadcrumbs) for HTML output.
1076
\row \li \c navigation.toctitles.inclusive (Since QDoc 6.3)
1077
\li If set to \c true, page(s) listed in \c navigation.toctitles
1078
will also appear in the navigation bar as a root item.
1079
\row \li \c navigation.trademarkspage (Since QDoc 6.8)
1080
\li Title of a page that documents trademarks mentioned in the
1081
documentation. See also \qdoccmd tm command.
1082
\endtable
1083
1084
For example:
1085
1086
\badcode
1087
# Common configuration
1088
navigation.homepage = index.html
1089
navigation.hometitle = "Qt $QT_VER"
1090
1091
# qtquick.qdocconf
1092
navigation.landingpage = "Qt Quick"
1093
navigation.cppclassespage = "Qt Quick C++ Classes"
1094
navigation.qmltypespage = "Qt Quick QML Types"
1095
\endcode
1096
1097
The above configuration produces the following navigation bar for \c Item QML type:
1098
1099
\badcode
1100
Qt 5.10 > Qt Quick > QML Types > Item QML Type
1101
\endcode
1102
1103
\target outputdir-variable
1104
\section1 outputdir
1105
1106
The \c outputdir variable specifies the directory where QDoc will
1107
put the generated documentation.
1108
1109
\badcode
1110
outputdir = $QTDIR/doc/html
1111
\endcode
1112
1113
locates the generated Qt reference documentation in
1114
$QTDIR/doc/html. For example, the documentation of the QWidget
1115
class is located in
1116
1117
\badcode
1118
$QTDIR/doc/html/qwidget.html
1119
\endcode
1120
1121
The associated images will be put in an \c images subdirectory.
1122
1123
\warning When running QDoc multiple times using the same output
1124
directory, all files from the previous run will be lost.
1125
1126
\target outputencoding-variable
1127
\section1 outputencoding
1128
1129
The \c outputencoding variable specifies the encoding used for the
1130
documentation generated by QDoc.
1131
1132
\badcode
1133
outputencoding = UTF-8
1134
\endcode
1135
1136
By default, the output encoding is \c ISO-8859-1 (Latin1) for
1137
compatibility with legacy documentation. When generating
1138
documentation for some languages, particularly non-European
1139
languages, this is not sufficient and an encoding such as UTF-8 is
1140
required.
1141
1142
QDoc will encode HTML using this encoding and generate the correct
1143
declarations to indicate to browsers which encoding is being
1144
used. The \l naturallanguage configuration variable should also be
1145
specified to provide browsers with a complete set of character
1146
encoding and language information.
1147
1148
See also \l outputencoding and \l naturallanguage.
1149
1150
\target outputformats-variable
1151
\section1 outputformats
1152
1153
The \c outputformats variable specifies the format(s) of
1154
the generated documentation.
1155
1156
Since Qt 5.11, QDoc supports the HTML and WebXML formats; since
1157
Qt 5.15, it can also generate the documentation in DocBook. If no
1158
\c outputformats are specified, QDoc generates the documentation
1159
in HTML (the default format). All output formats can be specified,
1160
with dedicated output directories and other settings. For example:
1161
1162
\badcode
1163
outputformats = WebXML HTML
1164
WebXML.nosubdirs = true
1165
WebXML.outputsubdir = webxml
1166
WebXML.quotinginformation = true
1167
\endcode
1168
1169
This generates HTML documentation using the default settings, as well
1170
as WebXML documentation into output subdirectory \e webxml.
1171
1172
\target outputprefixes-variable
1173
\section1 outputprefixes
1174
1175
The \c outputprefixes variable specifies a mapping between types of files
1176
and the prefixes to prepend to the output file names in the generated
1177
documentation.
1178
1179
QDoc supports adding an output prefix to the file names of QML type, C++
1180
class, namespace, and header file reference pages.
1181
1182
\badcode
1183
outputprefixes = QML CPP
1184
outputprefixes.QML = uicomponents-
1185
outputprefixes.CPP = components-
1186
\endcode
1187
1188
By default, files containing the API documentation for QML types
1189
are prefixed with \c {qml-}. In the above example, the prefix \c
1190
{uicomponents-} is used instead.
1191
1192
Likewise, C++ type documentation pages are prefixed with \c {components-}
1193
in the above example. By default, C++ type pages have no prefix.
1194
1195
\target outputsuffixes-variable
1196
\section1 outputsuffixes
1197
1198
The \c outputsuffixes variable specifies a mapping between types of
1199
files and suffixes to apply to the module or type name as they appear
1200
in the output file names.
1201
1202
QDoc supports adding an output suffix to the file names of module pages,
1203
QML type, C++ class, namespace, and header file reference pages.
1204
1205
By default, no suffix is used. The QML output suffix, if defined, is
1206
applied as a suffix to the module name as it appears in the file names
1207
of QML type and QML module pages.
1208
1209
File names for C++ types do not include the module name. The CPP
1210
output suffix, if defined, is applied as a suffix for the type name.
1211
1212
\badcode
1213
outputsuffixes = QML CPP
1214
{outputsuffixes.QML,outputsuffixes.CPP} = -tp
1215
\endcode
1216
1217
With the definitions above, given a QML module name \e FooBar and the default
1218
\l {outputprefixes-variable}{output prefix} (\c {qml-}), the name of
1219
the generated file for a QML type \e FooWidget is
1220
\c qml-foobar-tp-foowidget.html.
1221
1222
Likewise, for a C++ class \e QFoobar, QDoc generates \c qfoobar-tp.html.
1223
1224
The \c outputsuffixes variable was introduced in QDoc 5.6.
1225
1226
\target qhp-variable
1227
\section1 qhp
1228
1229
The \c qhp sub-variables are used to define the information to be
1230
written out to Qt Help Project (\c{qhp}) files.
1231
1232
See the \l{Creating Help Project Files} chapter for information
1233
about this process.
1234
1235
Since QDoc 6.6, setting the base \c qhp variable to \c true means
1236
that a valid help project configuration is expected:
1237
1238
\badcode
1239
qhp = true
1240
\endcode
1241
1242
Then, if a project configuration did not define \c {qhp.projects},
1243
QDoc issues a warning. This is useful for ensuring that all
1244
documentation projects with a shared top-level \e .qdocconf file
1245
(as in Qt) are configured correctly.
1246
1247
To turn off the warning, set the variable to \c false.
1248
1249
\target sourcedirs-variable
1250
\section1 sourcedirs
1251
1252
The \c sourcedirs variable specifies the directories containing
1253
the \c .cpp or \c .qdoc files used in the documentation.
1254
1255
\badcode
1256
sourcedirs += .. \
1257
../../../examples/gui/doc/src
1258
\endcode
1259
1260
When executed, the first thing QDoc will do is to read through the
1261
headers specified in the \l {header-command} {\c header} variable,
1262
and the ones located in the directories specified in the \c
1263
headerdir variable (including all subdirectories), building an
1264
internal structure of the classes and their functions.
1265
1266
Then it will read through the sources specified in the \l
1267
{sources} {\c sources}, and the ones located in the directories
1268
specified in the \l {sourcedirs} {\c sourcedirs} variable
1269
(including all subdirectories), merging the documentation with the
1270
structure it retrieved from the header files.
1271
1272
If both the \c sources and \c sourcedirs variables are defined,
1273
QDoc will read through both, first \l {sources} {\c sources} then
1274
\c sourcedirs.
1275
1276
In the specified directories, QDoc will only read the files with
1277
the \c fileextensions specified in the \l {sources.fileextensions}
1278
{\c sources.fileextensions} variable. The files specified by \l {sources}
1279
{\c sources} will be read independent of their fileextensions.
1280
1281
See also \l {sources-variable} {sources} and
1282
\l {sources.fileextensions-variable} {sources.fileextensions}.
1283
1284
\target sourceencoding-variable
1285
\section1 sourceencoding
1286
1287
The \c sourceencoding variable specifies the encoding used for the
1288
source code and documentation.
1289
1290
\badcode
1291
sourceencoding = UTF-8
1292
\endcode
1293
1294
By default, the source encoding is \c ISO-8859-1 (Latin1) for
1295
compatibility with legacy documentation. For some languages,
1296
particularly non-European languages, this is not sufficient and an
1297
encoding such as UTF-8 is required.
1298
1299
Although QDoc will use the encoding to read source and
1300
documentation files, limitations of C++ compilers may prevent you
1301
from using non-ASCII characters in source code comments. In cases
1302
like these, it is possible to write API documentation completely
1303
in documentation files.
1304
1305
See also \l {naturallanguage-variable} {naturallanguage} and
1306
\l {outputencoding-variable} {outputencoding}.
1307
1308
\target sources-variable
1309
\section1 sources
1310
1311
The \c sources variable allows you to specify individual source
1312
files in addition to those located in the directories specified by
1313
the \l {sourcedirs-variable} {sourcedirs} variable.
1314
1315
\badcode
1316
sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
1317
$QTDIR/src/gui/widgets/qpushbutton.cpp
1318
\endcode
1319
1320
When processing the \c sources variable, QDoc behaves in the same
1321
way as it does when processing the \l {sourcedirs-variable}
1322
{sourcedirs} variable. For more information, see the \l
1323
{sourcedirs-variable} {sourcedirs} variable.
1324
1325
See also \l {sourcedirs-variable} {sourcedirs}.
1326
1327
\target sources.fileextensions-variable
1328
\section1 sources.fileextensions
1329
1330
The \c sources.fileextensions variable filters the files within a
1331
source directory.
1332
1333
When processing the source files specified in the \l {sourcedirs}
1334
{\c sourcedirs} variable, QDoc will only read the files with the
1335
fileextensions specified in the \c sources.fileextensions
1336
variable. In this way QDoc avoid spending time reading irrelevant
1337
files.
1338
1339
The default extensions are *.c++, *.cc, *.cpp, *.cxx, *.mm, *.qml
1340
and *.qdoc.
1341
1342
The extensions are given as standard wildcard expressions. You
1343
can add a file extension to the filter using '+='. For example:
1344
1345
\badcode
1346
sources.fileextensions += *.CC
1347
\endcode
1348
1349
\warning The above assignment may not work as described.
1350
1351
See also \l {sourcedirs-variable} {sourcedirs} and \l
1352
{sources-variable} {sources}.
1353
1354
1355
\target spurious-variable
1356
\section1 spurious
1357
1358
The \c spurious variable excludes specified QDoc warnings from the
1359
output. The warnings are specified using standard wildcard
1360
expressions.
1361
1362
\badcode
1363
spurious = "Cannot find .*" \
1364
"Missing .*"
1365
\endcode
1366
1367
makes sure that warnings matching either of these expressions,
1368
will not be part of the output when running QDoc. For example
1369
would the following warning be omitted from the output:
1370
1371
\badcode
1372
src/opengl/qgl_mac.cpp:156: Missing parameter name
1373
\endcode
1374
1375
\target syntaxhighlighting
1376
\section1 syntaxhighlighting
1377
1378
The \c syntaxhighlighting variable specifies whether QDoc should
1379
perform syntax highlighting on source code quoted in the
1380
documentation it generates.
1381
1382
\badcode
1383
syntaxhighlighting = true
1384
\endcode
1385
1386
will enable syntax highlighting for all supported programming
1387
languages.
1388
1389
\target tabsize-variable
1390
\section1 tabsize
1391
1392
The \c tabsize variable defines the size of a tab character.
1393
1394
\badcode
1395
tabsize = 4
1396
\endcode
1397
1398
will give the tab character the size of 4 spaces. The default
1399
value of the variable is 8, and doesn't need to be specified.
1400
1401
\target tagfile-variable
1402
\section1 tagfile
1403
1404
The \c tagfile variable specifies the Doxygen tag file to be
1405
written when HTML is generated.
1406
1407
\target version-variable
1408
\section1 version
1409
1410
The \c version variable specifies the version number of the
1411
documented software.
1412
1413
\badcode
1414
version = 5.6.0
1415
\endcode
1416
1417
When a version number is specified (using the \tt{\l version} or
1418
\tt {\l versionsym} variables in a \c .qdocconf file), it is
1419
accessible through the corresponding \\version command for use in
1420
the documentation.
1421
1422
\warning The \\version command's functionality is not fully
1423
implemented; currently it only works within raw HTML code.
1424
1425
See also \l versionsym.
1426
1427
\target versionsym-variable
1428
\section1 versionsym
1429
1430
The \c versionsym variable specifies a C++ preprocessor symbol
1431
that defines the version number of the documented software.
1432
1433
\badcode
1434
versionsym = QT_VERSION_STR
1435
\endcode
1436
1437
QT_VERSION_STR is defined in qglobal.h as follows
1438
1439
\badcode
1440
#define QT_VERSION_STR "5.14.1"
1441
\endcode
1442
1443
When a version number is specified (using the \tt{\l version} or
1444
\tt {\l versionsym} variables in a \c .qdocconf file), it is
1445
accessible through the corresponding \\version command for use in
1446
the documentation.
1447
1448
\warning The \\version command's functionality is not fully
1449
implemented. Currently, it only works within raw HTML code.
1450
1451
See also \l {version} {\\version}.
1452
1453
\target warninglimit-variable
1454
\section1 warninglimit
1455
1456
The \c warninglimit variable sets the maximum number of documentation
1457
warnings allowed. If this limit is exceeded, QDoc continues as normal
1458
but exits with the warning count as the error code. If the limit was
1459
not exceeded or \c warninglimit was not defined, QDoc process exits
1460
with 0, assuming there were no other critical errors.
1461
1462
Setting the \c warninglimit to \c 0 means failure on any warning.
1463
1464
\note By default, QDoc does not enforce the warning limit. Enable it
1465
with \c {warninglimit.enabled = true} or by defining
1466
the \c QDOC_ENABLE_WARNINGLIMIT environment variable.
1467
1468
For example,
1469
1470
\badcode
1471
# Fail the documentation build if we have more than 100 warnings
1472
warninglimit = 100
1473
warninglimit.enabled = true
1474
\endcode
1475
1476
The \c warninglimit variable was introduced in Qt 5.11.
1477
*/
1478
1479
/*!
1480
\page 22-creating-help-project-files.html
1481
\previouspage Generic Configuration Variables
1482
\nextpage Format-specific Configuration Variables
1483
1484
\title Creating Help Project Files
1485
1486
\section1 Overview
1487
1488
Qt Assistant uses a system for managing Qt documentation that requires
1489
QDoc to generate inventories of files.
1490
1491
QDoc allows configuration variables to be used to specify which pages are
1492
to be used in each documentation set it generates. These are specified as
1493
subvariables of the \c qhp variable with each set declared using a unique
1494
identifier as a subvariable.
1495
1496
For example, the configuration file for the Qt Quick documentation set
1497
specifies information about the set as subvariables with the
1498
\c{qhp.QtQuick} prefix:
1499
1500
\badcode
1501
qhp.projects = QtQuick
1502
1503
qhp.QtQuick.file = qtquick.qhp
1504
qhp.QtQuick.namespace = org.qt-project.qtquick.$QT_VERSION_TAG
1505
qhp.QtQuick.virtualFolder = qtquick
1506
qhp.QtQuick.indexTitle = Qt Quick
1507
qhp.QtQuick.indexRoot =
1508
1509
qhp.QtQuick.subprojects = qmltypes classes examples
1510
1511
qhp.QtQuick.subprojects.qmltypes.title = QML Types
1512
qhp.QtQuick.subprojects.qmltypes.indexTitle = Qt Quick QML Types
1513
qhp.QtQuick.subprojects.qmltypes.selectors = qmlclass
1514
qhp.QtQuick.subprojects.qmltypes.sortPages = true
1515
1516
qhp.QtQuick.subprojects.classes.title = Classes
1517
qhp.QtQuick.subprojects.classes.title = C++ Classes
1518
qhp.QtQuick.subprojects.classes.indexTitle = Qt Quick C++ Classes
1519
qhp.QtQuick.subprojects.classes.selectors = class fake:headerfile
1520
qhp.QtQuick.subprojects.classes.sortPages = true
1521
1522
qhp.QtQuick.subprojects.examples.title = Examples
1523
qhp.QtQuick.subprojects.examples.indexTitle = Qt Quick Examples and Tutorials
1524
qhp.QtQuick.subprojects.examples.selectors = fake:example
1525
\endcode
1526
1527
The documentation set may include one or more subprojects, which are added
1528
to the table of contents under the name specified by \c title. The page
1529
in the documentation referred to by the \c indexTitle acts as the index page
1530
for the subproject. The page types to list under the subproject are specified
1531
by \c selectors. The entries are alphabetically sorted if \c sortPages is set
1532
to \c true.
1533
1534
\section2 Using Selectors
1535
1536
The \c selectors property specifies which page types are listed under the
1537
table of contents entry for a subproject. Multiple selectors can be listed,
1538
separated by whitespace.
1539
1540
\table
1541
\header \li Selector \li Description
1542
\row \li \c namespace \li Namespaces
1543
\row \li \c class \li Classes
1544
\row \li \c qmltype \li QML Types
1545
\row \li \c qmlclass \li Alias for \c qmltype.
1546
\row \li \c module[:name] \li C++ modules or members of the module
1547
with a specified name.
1548
\row \li \c qmlmodule[:name] \li QML modules or members of the module
1549
with a specified name.
1550
\row \li \c doc[:subtype] \li Documentation pages with a specified
1551
\c subtype. Multiple subtypes can be
1552
listed as a comma-separated list.
1553
\row \li \c fake \li Alias for \c doc.
1554
\row \li \c group[:groupname] \li Documentation pages for members of a
1555
specified group, as added using the
1556
\l {ingroup-command}
1557
{\\ingroup} groupname command.
1558
Multiple group names can be listed as
1559
a comma-separated list.
1560
(Introduced in QDoc 5.6).
1561
\endtable
1562
1563
Available subtypes for the \c doc selector:
1564
1565
\table
1566
\header \li Subtype \li Description
1567
\row \li \c example \li Examples
1568
\row \li \c headerfile \li Header files
1569
\row \li \c page \li Documentation pages defined with the
1570
\l {page-command} {\\page} command.
1571
\endtable
1572
1573
For example, the following configuration would select example pages and
1574
pages that include the \c {\ingroup tutorials} command:
1575
1576
\badcode
1577
qhp.QtQuickControls.subprojects = examples
1578
qhp.QtQuickControls.subprojects.examples.title = Examples and Tutorials
1579
qhp.QtQuickControls.subprojects.examples.indexTitle = Qt Quick Controls Examples
1580
qhp.QtQuickControls.subprojects.examples.selectors = doc:example group:tutorials
1581
qhp.QtQuickControls.subprojects.examples.sortPages = true
1582
\endcode
1583
1584
\section2 Adding Table of Contents
1585
1586
To create a table of contents for a manual, create a subproject with
1587
a \c{type} property and set it to \c{manual}. The page in the documentation
1588
referred to by the \c{indexTitle} property must contain a list of links
1589
that acts as a table of contents for the whole manual. QDoc will take the
1590
information in this list and create a table of contents for the subproject.
1591
1592
For example, the configuration file for Qt Creator defines only one
1593
subproject for its documentation, including all the documentation in a
1594
single manual:
1595
1596
\badcode
1597
qhp.QtCreator.subprojects = manual
1598
qhp.QtCreator.subprojects.manual.title = Qt Creator Manual
1599
qhp.QtCreator.subprojects.manual.indexTitle = Qt Creator Manual
1600
qhp.QtCreator.subprojects.manual.type = manual
1601
\endcode
1602
1603
In this example, the page entitled "Qt Creator Manual" contains a nested
1604
list of links to pages in the documentation which is duplicated in
1605
Qt Assistant's Contents tab.
1606
*/
1607
1608
/*!
1609
\page 24-qdoc-configuration-htmlvariables.html
1610
\previouspage Creating Help Project Files
1611
\nextpage Supporting Derived Projects
1612
1613
\keyword HTML Specific Configuration Variables
1614
\title Format-specific Configuration Variables
1615
1616
The format-specific configuration variables define the generated
1617
documentation's style, or define the contents of the
1618
documentation's footer or postheader.
1619
1620
Some of the configuration values are relevant only for the HTML
1621
output format and their values contain raw HTML.
1622
1623
\target HTML.footer-variable
1624
\section1 HTML.footer
1625
1626
The \c HTML.footer variable defines the content of the generated
1627
HTML documentation's footer.
1628
1629
The footer is rendered at the bottom of the generated
1630
documentation page.
1631
1632
The variable's value is given as raw HTML code enclosed by
1633
quotation marks. Note that if the value spans several lines, each
1634
line needs to be enclosed by quotation marks.
1635
1636
\badcode
1637
HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
1638
...
1639
"</tr></table></div></address>"
1640
\endcode
1641
1642
\target FORMAT.nosubdirs
1643
\section1 <FORMAT>.nosubdirs
1644
1645
A boolean value which, when \c true, enables single-directory output
1646
mode; all generated files go to \l {FORMAT.outputsubdir} directory,
1647
instead of a subdirectory based on the documentation project name.
1648
1649
\target FORMAT.outputsubdir
1650
\section1 <FORMAT>.outputsubdir
1651
1652
Defines the subdirectory under \l outputdir where documentation is
1653
generated.
1654
1655
\badcode
1656
HTML.nosubdirs = true
1657
HTML.outputsubdir = html
1658
\endcode
1659
1660
With above, the output goes to \c {<outputdir>/html}.
1661
1662
\target HTML.postheader-variable
1663
\section1 HTML.postheader
1664
1665
The \c HTML.postheader variable defines the content of the
1666
generated HTML documentation's postheader.
1667
1668
The header is rendered at the top of the generated documentation
1669
page.
1670
1671
The variable's value is given as raw HTML enclosed by quotation
1672
marks. Note that if the value spans several lines, each line needs
1673
to be enclosed by quotation marks.
1674
1675
\badcode
1676
HTML.postheader = "<table border=\"0\"..." \
1677
...
1678
"<img src=\"images/qt-logo.png\" \
1679
"align=\"right\" width=\"203\" height=\"32\""\
1680
"border=\"0\" />" \
1681
"</td></tr>" \
1682
"</table>"
1683
\endcode
1684
1685
The complete variable entry in \l qtgui.qdocconf provides the
1686
standard header of the \l {http://doc.qt.io/qt-5/qtgui-index.html}
1687
{Qt GUI Documentation}.
1688
1689
\target FORMAT.quotinginformation
1690
\section1 <FORMAT>.quotinginformation
1691
1692
A boolean value which, when \c true, generates references to
1693
quoted content (for example, \l {quotefromfile-command}{\\quotefromfile}
1694
and \l {snippet-command}{\\snippet} commands) instead of including
1695
the content directly.
1696
1697
Used currently for the \c WebXML output format.
1698
1699
\badcode
1700
WebXML.quotinginformation = true
1701
\endcode
1702
1703
\target HTML.style-variable
1704
\section1 HTML.style
1705
1706
The HTML.style variable defines the style for
1707
the generated HTML documentation.
1708
1709
The variable's value is given as raw HTML enclosed by quotation
1710
marks. Note that if the value spans several lines, each line needs
1711
to be enclosed by quotation marks.
1712
1713
\badcode
1714
HTML.style = "h3.fn,span.fn" \
1715
"{ margin-left: 1cm; text-indent: -1cm; }\n" \
1716
"a:link { color: #004faf; text-decoration: none }\n" \
1717
"a:visited" \
1718
"{ color: #672967; text-decoration: none }\n" \
1719
"td.postheader { font-family: sans-serif }\n" \
1720
"tr.address { font-family: sans-serif }\n" \
1721
"body { background: #ffffff; color: black; }"
1722
\endcode
1723
1724
\target HTML.stylesheets-variable
1725
\section1 HTML.stylesheets
1726
1727
The HTML.stylesheets variable defines a list of stylesheets
1728
to use for the generated HTML documentation.
1729
1730
Using separate stylesheets for the documentation makes it easier
1731
to customize and experiment with the style used once the contents
1732
has been generated. Typically, it is only necessary to define a
1733
single stylesheet for any set of documentation; for example:
1734
1735
\badcode
1736
HTML.stylesheets = path/to/classic.css
1737
\endcode
1738
1739
QDoc expects to find stylesheets in the directory containing the
1740
\l qtgui.qdocconf file, and it will copy those specified to the output
1741
directory alongside the HTML pages.
1742
1743
\target HTML.tocdepth
1744
\section1 <FORMAT>.tocdepth
1745
1746
The \c {<FORMAT>.tocdepth} variable defines how many document sections
1747
are printed in the table of contents. Setting tocdepth to \c 0 disables
1748
the table of contents while leaving it undefined prints all document
1749
sections.
1750
1751
Currently only has an effect for the HTML format:
1752
1753
\badcode
1754
HTML.tocdepth = 3
1755
\endcode
1756
*/
1757
1758
/*!
1759
\page 25-qdoc-configuration-derivedprojects.html
1760
\previouspage Format-specific Configuration Variables
1761
\nextpage Example Manifest Files
1762
1763
\title Supporting Derived Projects
1764
1765
Some configuration variables allow you to use QDoc to support
1766
Qt-based projects. They allow your project to contain links to the
1767
online Qt documentation, which means that QDoc will be able to
1768
create links to the class reference documentation, without any
1769
explicit linking command.
1770
1771
\target description-variable
1772
\section1 description
1773
1774
The description variable holds a short description of the
1775
associated project.
1776
1777
See also \l project.
1778
1779
\target indexes-variable
1780
\section1 indexes
1781
1782
The \c indexes variable defines a set of paths to index files to load.
1783
1784
\badcode
1785
indexes = \
1786
$QT_INSTALL_DOCS/qtcore/qtcore.index \
1787
$SOME_OTHER_PROJECT/doc/foo.index
1788
\endcode
1789
1790
The \c indexes variable provides an alternative to \l depends for
1791
defining project's dependencies. As direct paths are provided, no
1792
\c -indexdir command line option(s) are required when invoking QDoc.
1793
1794
It is possible to define dependencies using either variable. Qt
1795
documentation only uses the \c depends variable.
1796
1797
See also \l depends, \l project and \l url.
1798
1799
\target productname-variable
1800
\section1 productname
1801
1802
Use the \c productname variable if the name of the product being documented
1803
is different from the name of the documentation \qdocvar project. This is
1804
particularly useful for larger documentation sets that consist of multiple
1805
documentation projects and/or modules, as it allows QDoc to generate the
1806
product name instead of project name in certain contexts, such as the
1807
\qdoccmd since command.
1808
1809
For example, Qt defines \e Qt as the \c productname, while each individual
1810
module defines its own \c project name. This allows authors to use the
1811
shorthand notation for the \qdoccmd since command.
1812
1813
This configuration variable was introduced to QDoc with Qt 6.9.
1814
1815
See also \qdoccmd {since}.
1816
1817
\target project-variable
1818
\section1 project
1819
1820
The \c project variable provides a name for the project associated
1821
with the \c .qdocconf file. This is a mandatory variable that all
1822
projects must set.
1823
1824
The project's name is used to form a file name for the associated
1825
project's \e index file.
1826
1827
\badcode
1828
project = QtCreator
1829
\endcode
1830
1831
This will cause an index file called \c qtcreator.index to be
1832
created.
1833
1834
If the project name contains whitespace or special characters,
1835
these are replaced with dashes ('-') in the generated index file
1836
name.
1837
1838
See also \l depends, \l indexes, and \l description.
1839
1840
\target url-variable
1841
\section1 url
1842
1843
The \c url variable holds the base URL for the
1844
documentation associated with the current project.
1845
1846
The URL is stored in the generated index file for the
1847
project. When we use the index on its own, QDoc will use this as
1848
the base URL when constructing links to classes, functions, and
1849
other things listed in the index.
1850
1851
\badcode
1852
project = QtCore
1853
description = Qt Core Reference Documentation
1854
url = https://doc.qt.io/qt/
1855
1856
...
1857
\endcode
1858
1859
This ensures that whenever QDoc generates
1860
references to entities in the Qt Core module, the base URL is
1861
\c https://doc.qt.io/qt/.
1862
1863
See also \l depends, \l indexes and \l {url.examples}.
1864
1865
\target url.examples-variable
1866
\section1 url.examples
1867
1868
The \c url.examples variable holds the base URL for the examples
1869
associated with the current project.
1870
1871
If defined, a link to the example project directory is generated
1872
at the end of each example documentation page. The \c url.examples
1873
variable refers to the root directory of the examples related to
1874
this project; it can be a link to an online repository (starting
1875
with \e http:// or \e https://), or to the local file system
1876
(\c file://).
1877
1878
If \c url.examples is not defined, QDoc will output a list of
1879
example's files and images instead.
1880
1881
For example, given these definitions:
1882
1883
\badcode
1884
url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
1885
examplesinstallpath = corelib
1886
\endcode
1887
1888
Then, for the following \l {example-command}{\\example} command:
1889
1890
\badcode *
1891
/\1!
1892
\example threads/semaphores
1893
...
1894
\1/
1895
\endcode
1896
1897
QDoc generates a link to
1898
\c https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores.
1899
1900
If the URL contains more components (for example, a query string)
1901
after the example path, \\1 can be used as a placeholder for the
1902
path:
1903
1904
\badcode
1905
url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
1906
examplesinstallpath = corelib
1907
\endcode
1908
1909
Given the same \\example command as above and assuming that
1910
\c $QT_VER expands to \c {5.13}, the generated URL is
1911
\c https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13.
1912
1913
\c {url.examples} variable was introduced in QDoc version 5.13.
1914
1915
See also \l url, \l examplesinstallpath, and \l {example-command}{\\example}.
1916
1917
\target howto
1918
\section1 How to Support Derived Projects
1919
1920
This feature makes use of the comprehensive indexes generated by
1921
QDoc when it creates the Qt reference documentation.
1922
1923
For example, \l qtgui.qdocconf (the configuration file for Qt GUI)
1924
contains the following variable definitions:
1925
1926
\badcode
1927
project = QtGui
1928
description = Qt GUI Reference Documentation
1929
url = http://doc.qt.io/qt/
1930
1931
...
1932
\endcode
1933
1934
The \l project variable name is used to form a file name for the
1935
index file; in this case the \c qtgui.index file is created. The \l
1936
url is stored in the index file. Afterwards, QDoc will use this
1937
as the base URL when constructing links to classes, functions,
1938
and other things listed in the index.
1939
1940
See also \l depends, \l indexes, \l project, and \l url.
1941
*/
1942
1943
/*!
1944
\page 26-qdoc-configuration-example-manifest-files.html
1945
\previouspage Supporting Derived Projects
1946
1947
\title Example Manifest Files
1948
1949
QDoc generates example-manifest.xml files that contain information about
1950
all documented examples. These files are used by Qt Creator to present a
1951
list of examples in its welcome screen and to link to their documentation.
1952
1953
\section1 Manifest XML Structure
1954
1955
A manifest file has the following structure:
1956
1957
\badcode
1958
<?xml version="1.0" encoding="UTF-8"?>
1959
<instructionals module="QtGui">
1960
<examples>
1961
<example
1962
name="Analog Clock Window"
1963
docUrl="qthelp://org.qt-project.qtgui.502/qtgui/analogclock.html"
1964
projectPath="gui/analogclock/analogclock.pro"
1965
imageUrl="qthelp://org.qt-project.qtgui.502/qtgui/images/analogclock-window.png">
1966
<description><![CDATA[The Analog Clock Window example shows how
1967
to draw the contents of a custom window.]]></description>
1968
<tags>analog,clock,window</tags>
1969
<fileToOpen>gui/analogclock/main.cpp</fileToOpen>
1970
</example>
1971
...
1972
</examples>
1973
</instructionals>
1974
\endcode
1975
1976
Each \c {<example>} element contains information about a name,
1977
description, the location of the project file and documentation,
1978
as well as a list of tags associated with the example.
1979
1980
\target metacontent
1981
\section1 Manifest Meta Content
1982
1983
It is possible to augment the manifest files with additional
1984
meta-content - that is, extra attributes and tags for selected
1985
examples, using the \c manifestmeta configuration command.
1986
1987
One use case for meta-content is highlighting a number of prominent
1988
examples. Another is improving search functionality by adding
1989
relevant keywords as tags for a certain category of examples.
1990
1991
The examples for which meta-content is applied to is specified using
1992
one or more filters. Matching examples to filters is done based on
1993
names, with each example name prefixed with a module name and a
1994
slash. Simple wildcard matching is supported; by using \c {*} at the
1995
end it's possible to match multiple examples with a single string.
1996
1997
Example:
1998
1999
\badcode
2000
manifestmeta.filters = highlighted sql webkit global
2001
2002
manifestmeta.highlighted.names = "QtGui/Analog Clock Window" \
2003
"QtWidgets/Analog Clock"
2004
manifestmeta.highlighted.attributes = isHighlighted:true
2005
2006
manifestmeta.sql.names = "QtSql/*"
2007
manifestmeta.sql.tags = database,sql
2008
2009
manifestmeta.webkit.names = "QtWebKitExamples/*"
2010
manifestmeta.webkit.tags = webkit
2011
2012
manifestmeta.global.names = *
2013
manifestmeta.global.tags = qt6
2014
\endcode
2015
2016
Above, an \c isHighlighted attribute is added to two examples. If
2017
the attribute value is omitted, QDoc uses the string \c {true} by
2018
default. Extra tags are added for Qt WebKit and Qt SQL examples, and
2019
another tag is applied to all examples by using just \c {*} as the
2020
match string.
2021
*/
2022
2023
/*!
2024
\page 21-1-minimum-qdocconf.html
2025
\previouspage qtgui.qdocconf
2026
\nextpage The QDoc Configuration File
2027
2028
\title minimum.qdocconf
2029
2030
\quotefile examples/minimum.qdocconf
2031
*/
2032
2033
/*!
2034
\page 21-2-qtgui-qdocconf.html
2035
\previouspage Supporting Derived Projects
2036
\nextpage minimum.qdocconf
2037
2038
\title qtgui.qdocconf
2039
2040
\quotefile files/qtgui.qdocconf
2041
*/
qttools
src
qdoc
qdoc
doc
qdoc-manual-qdocconf.qdoc
Generated on Sat Sep 21 2024 01:06:19 for Qt by
1.12.0